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:
Inaky Perez-Gonzalez 2016-06-15 12:15:24 -07:00
commit 9752d3d6b6
3 changed files with 82 additions and 5 deletions

View file

@ -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
*******************************

View file

@ -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).

View file

@ -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);
/**
* @}