patrick/zephyr
1
0
Fork 0
Code Issues Pull requests Actions 8 Packages Projects Releases Wiki Activity

doc: fix code references in typedef.rst

Browse source 
Makes no sense to integrate the whole file for just a few lines, so
defaulted to remove the inclusion and just copy the lines that are
interesting.

Change-Id: I84a2218063ca7368678402b1123da34efae14f27
Signed-off-by: Inaky Perez-Gonzalez <inaky.perez-gonzalez@intel.com>
This commit is contained in:
Inaky Perez-Gonzalez 2016-06-14 17:09:41 -07:00
parent 60f5c97dd0
commit 5fae13e38d
1 changed files with 15 additions and 15 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

30
doc/contribute/doxygen/typedefs.rst
View file

@ -28,11 +28,13 @@ Type Definition Documentation Example
Correct:
.. literalinclude:: irq_test_common_commented.h
:language: c
:lines: 69-73
:emphasize-lines: 1, 3, 4
:linenos:
.. code-block:: c
/** Declares a void-void function pointer to test the ISR. */
typedef void (*vvfn)(void);
/** Declares a void-void_pointer function pointer to test the ISR. */
typedef void (*vvpfn)(void *);
Lines 1 and 4 name the type that is being used and with what purpose.
Even if the purpose is the same, since the types are different, two
@ -42,14 +44,12 @@ appropriately.
Incorrect:
.. literalinclude:: ../../../../samples/include/irq_test_common.h
:language: c
:lines: 67-72
:emphasize-lines: 3, 4
:linenos:
.. code-block:: c
The comments on lines 3 and 4 offer little insight into the code's behavior.
Furthermore, they do not start with
:literal:`/**` and end with :literal:`*/`. Doxygen won't add the
information to the documentation nor link it properly to the complex
type documentation.
typedef void (*vvfn)(void); /* void-void function pointer */
typedef void (*vvpfn)(void *); /* void-void_pointer function pointer */
The comments offer little insight into the code's behavior.
Furthermore, they do not start with :literal:`/**` and end with
:literal:`*/`. Doxygen won't add the information to the documentation
nor link it properly to the complex type documentation.