doc: fix warnings "Error when parsing function declaration." due to __deprecated
Sphinx's parser gets all confused; add a workaround using @fn, document the workaround in the contribution section; bug filed with Sphinx for a permanent sollution. Change-Id: I0200add092da27206b9d006bb13110c4cc37d0e4 Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
This commit is contained in:
parent
85c64466ff
commit
9752d3d6b6
3 changed files with 82 additions and 5 deletions
|
@ -71,6 +71,79 @@ Simplified template:
|
|||
and the function's signature. This ensures that Doxygen can link the comment
|
||||
to the function.
|
||||
|
||||
Workarounds
|
||||
***********
|
||||
|
||||
When adding qualifiers to a function declaration, like *__deprecated*
|
||||
(or *ALWAYS_INLINE*, or any others), for example:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/**
|
||||
* @brief Register a task IRQ object.
|
||||
*
|
||||
* This routine connects a task IRQ object to a system interrupt based
|
||||
* upon the specified IRQ and priority values.
|
||||
*
|
||||
* IRQ allocation is done via the microkernel server fiber, making simultaneous
|
||||
* allocation requests single-threaded.
|
||||
*
|
||||
* @param irq_obj IRQ object identifier.
|
||||
* @param irq Request IRQ.
|
||||
* @param priority Requested interrupt priority.
|
||||
* @param flags IRQ flags.
|
||||
*
|
||||
* @return assigned interrupt vector if successful, INVALID_VECTOR if not
|
||||
*/
|
||||
uint32_t __deprecated task_irq_alloc(kirq_t irq_obj, uint32_t irq,
|
||||
uint32_t priority, uint32_t flags);
|
||||
|
||||
the *Sphinx* parser can get confused with errors such as::
|
||||
|
||||
doc/api/microkernel_api.rst:35: WARNING: Error when parsing function declaration.
|
||||
If the function has no return type:
|
||||
Error in declarator or parameters and qualifiers
|
||||
Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 9]
|
||||
uint32_t __deprecated task_irq_alloc(kirq_t irq_obj, uint32_t irq, uint32_t priority, uint32_t flags)
|
||||
---------^
|
||||
If the function has a return type:
|
||||
Error in declarator or parameters and qualifiers
|
||||
If pointer to member declarator:
|
||||
Invalid definition: Expected '::' in pointer to member (function). [error at 22]
|
||||
uint32_t __deprecated task_irq_alloc(kirq_t irq_obj, uint32_t irq, uint32_t priority, uint32_t flags)
|
||||
----------------------^
|
||||
If declarator-id:
|
||||
Invalid definition: Expecting "(" in parameters_and_qualifiers. [error at 22]
|
||||
uint32_t __deprecated task_irq_alloc(kirq_t irq_obj, uint32_t irq, uint32_t priority, uint32_t flags)
|
||||
----------------------^
|
||||
... <etc etc>...
|
||||
|
||||
a workaround is to name with *@fn* the function:
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
/**
|
||||
* @fn uint32_t task_irq_alloc(kirq_t irq_obj, uint32_t irq,
|
||||
* uint32_t priority, uint32_t flags)
|
||||
* @brief Register a task IRQ object.
|
||||
*
|
||||
* This routine connects a task IRQ object to a system interrupt based
|
||||
* upon the specified IRQ and priority values.
|
||||
*
|
||||
* IRQ allocation is done via the microkernel server fiber, making simultaneous
|
||||
* allocation requests single-threaded.
|
||||
*
|
||||
* @param irq_obj IRQ object identifier.
|
||||
* @param irq Request IRQ.
|
||||
* @param priority Requested interrupt priority.
|
||||
* @param flags IRQ flags.
|
||||
*
|
||||
* @return assigned interrupt vector if successful, INVALID_VECTOR if not
|
||||
*/
|
||||
|
||||
This has been reported to the Sphinx developers
|
||||
(https://github.com/sphinx-doc/sphinx/issues/2682).
|
||||
|
||||
Function Documentation Examples
|
||||
*******************************
|
||||
|
||||
|
|
|
@ -264,6 +264,7 @@ static inline int gpio_pin_read(struct device *port, uint32_t pin,
|
|||
}
|
||||
|
||||
/**
|
||||
* @fn int gpio_set_callback(struct device *port, gpio_callback_t callback)
|
||||
* @brief Former way of setting the application's callback.
|
||||
* @param port Pointer to the device structure for the driver instance.
|
||||
* @param callback Application's callback (or NULL to unset).
|
||||
|
|
|
@ -37,7 +37,8 @@ extern "C" {
|
|||
#define INVALID_VECTOR 0xFFFFFFFF
|
||||
|
||||
/**
|
||||
*
|
||||
* @fn uint32_t task_irq_alloc(kirq_t irq_obj, uint32_t irq,
|
||||
* uint32_t priority, uint32_t flags)
|
||||
* @brief Register a task IRQ object.
|
||||
*
|
||||
* This routine connects a task IRQ object to a system interrupt based
|
||||
|
@ -53,11 +54,12 @@ extern "C" {
|
|||
*
|
||||
* @return assigned interrupt vector if successful, INVALID_VECTOR if not
|
||||
*/
|
||||
extern uint32_t __deprecated task_irq_alloc(kirq_t irq_obj, uint32_t irq,
|
||||
uint32_t __deprecated task_irq_alloc(kirq_t irq_obj, uint32_t irq,
|
||||
uint32_t priority, uint32_t flags);
|
||||
|
||||
/**
|
||||
*
|
||||
* @fn void task_irq_ack(kirq_t irq_obj)
|
||||
* @brief Re-enable a task IRQ object's interrupt.
|
||||
*
|
||||
* This re-enables the interrupt for a task IRQ object.
|
||||
|
@ -66,9 +68,10 @@ extern uint32_t __deprecated task_irq_alloc(kirq_t irq_obj, uint32_t irq,
|
|||
*
|
||||
* @return N/A
|
||||
*/
|
||||
extern void __deprecated task_irq_ack(kirq_t irq_obj);
|
||||
void __deprecated task_irq_ack(kirq_t irq_obj);
|
||||
|
||||
/**
|
||||
* @fn int task_irq_wait(kirq_t irq_obj, int32_t timeout)
|
||||
* @brief Wait for task IRQ to signal an interrupt.
|
||||
*
|
||||
* This routine waits up to @a timeout ticks for the IRQ object @a irq_obj
|
||||
|
@ -86,7 +89,7 @@ extern void __deprecated task_irq_ack(kirq_t irq_obj);
|
|||
* @a timeout = TICKS_NONE.
|
||||
* @sa TICKS_NONE, TICKS_UNLIMITED
|
||||
*/
|
||||
extern int __deprecated task_irq_wait(kirq_t irq_obj, int32_t timeout);
|
||||
int __deprecated task_irq_wait(kirq_t irq_obj, int32_t timeout);
|
||||
|
||||
/**
|
||||
* @}
|
||||
|
|
Loading…
Add table
Add a link
Reference in a new issue