michaelh/zephyr
1
0
Fork 0
Code Releases Activity

doc: Edit functions.rst

Browse source 
Edited functions.rst for coherence.
Added hello_wrong.c for usability.

Change-Id: I9f01139f0d8d3cde1f7c439c7a1fa38cd33139b8
Signed-off-by: Gerardo Aceves <gerardo.aceves@intel.com>
This commit is contained in:
Gerardo Aceves 2016-02-11 13:04:38 -06:00 • committed by Gerrit Code Review
commit 342d7e2e96
2 changed files with 45 additions and 14 deletions
Download patch file Download diff file Expand all files Collapse all files

29
doc/collaboration/code/doxygen/functions.rst
View file

@ -79,19 +79,20 @@ Example 1
Take the very simple function :c:func:`taskA()`:
.. literalinclude:: ../../../../samples/synchronization/microkernel/src/hello.c
.. literalinclude:: hello_wrong.c
:language: c
:lines: 77-85
:emphasize-lines: 3, 6
:lines: 1-12
:emphasize-lines: 4-6, 10, 12
:linenos:
The highlighted lines show comments that would not be added to the
documentation. That is unacceptable. The appropriate way to document
The highlighted lines contain comments that will be missing from the generated
documentation. To avoid this, pay careful attention to your commenting syntax.
This example shows good commenting syntax.
:c:func:`taskA()` is:
.. literalinclude:: hello_commented.c
:language: c
:lines: 97-110
:lines: 83-96
:emphasize-lines: 5-7, 11, 13
:linenos:
@ -105,15 +106,15 @@ Example 2
=========
Take the more complex function hello_loop():
.. literalinclude:: ../../../../samples/synchronization/microkernel/src/hello.c
.. literalinclude:: hello_wrong.c
:language: c
:lines: 56-76
:emphasize-lines: 1, 3-5, 7, 8, 13, 16
:lines: 14-31
:emphasize-lines: 1, 3-5, 7-9,13-16
:linenos:
The function parameters have been documented using the correct Doxygen
command, yet notice line 1. The comment block was not started with
:literal:`/**` and, therefore, Doxygen will not parse it correctly.
:literal:`/**` so, Doxygen will not parse it correctly.
The parameters have been documented using the \\param command. This is
equivalent to using @param but incorrect according to these guidelines.
@ -124,15 +125,15 @@ Notice that there is no blank line between the comment and the
function's signature, lines 7 and 8. This allows Doxygen to correctly
link the comment to the function.
Lines 13 and 16 contain two comments that will not be included by Doxygen
in the documentation. To include that information, use the brief description or the detailed
description inside the comment block.
Lines 13-16 contain comments that will not be included by Doxygen
in the documentation. To include that information, use the brief description
or the detailed description inside the comment block.
Remember that variables must be documented separately. See
:ref:`variables` for more details.
.. literalinclude:: hello_commented.c
:language: c
:lines: 72-95
:lines: 58-81
:emphasize-lines: 2, 4-7, 9-11, 19, 21
:linenos:

30
doc/collaboration/code/doxygen/hello_wrong.c Normal file
View file

@ -0,0 +1,30 @@
/*This is a hello world example*/
/*taskA exchanges hello messages with taskB*/
/*
* @brief Does Hello message.
* -Calls function helloLoop.
*/
void taskA(void)
{
helloLoop(__func__, TASKBSEM, TASKASEM);
}
#else
/* @brief A loop saying hello.
*
\param taskname The task's identification string.
\param mySem The task's semaphore.
\param otherSem The other task's semaphore.
*
*/
void taskA(void)
{
helloLoop(__func__, TASKBSEM, TASKASEM);
}
#else
/* Actions:
*
* -# Ouputs "Hello World!".
* -# Waits, then lets another task run.
*/