geda:devel-tips
Differences
This shows you the differences between two versions of the page.
| Both sides previous revision Previous revision | Next revision Both sides next revision | ||
|
geda:devel-tips [2012/02/20 15:14] 127.0.0.1 external edit |
geda:devel-tips [2012/05/15 08:15] vzh Added C formatting |
||
|---|---|---|---|
| Line 20: | Line 20: | ||
| If you want to see Doxygen's ideas on how to format documentation see the [[http://www.stack.nl/~dimitri/doxygen/docblocks.html|Doxygen website]]. The individual commands are documented [[http://www.stack.nl/~dimitri/doxygen/commands.html|here]]. There is also a very handy Doxygen [[http://www.digilife.be/quickreferences/QRC/Doxygen%20Quick%20Reference.pdf|quick reference card]]. | If you want to see Doxygen's ideas on how to format documentation see the [[http://www.stack.nl/~dimitri/doxygen/docblocks.html|Doxygen website]]. The individual commands are documented [[http://www.stack.nl/~dimitri/doxygen/commands.html|here]]. There is also a very handy Doxygen [[http://www.digilife.be/quickreferences/QRC/Doxygen%20Quick%20Reference.pdf|quick reference card]]. | ||
| - | The following sections provide an introduction on how gschem and libgeda are customarily documented. Note that the QT style of **/*! comment goes here */** for a Doxygen-enabled comment is preferred. | + | The following sections provide an introduction on how gschem and libgeda are customarily documented. Note that the QT style of **%%/*! comment goes here */%%** for a Doxygen-enabled comment is preferred. |
| ==== Documenting Files ==== | ==== Documenting Files ==== | ||
| When starting a new file, you obviously need to have the normal GNU license text. After the GNU License you should include a file comment describing what the file is for and any other descriptions that apply to the whole file. | When starting a new file, you obviously need to have the normal GNU license text. After the GNU License you should include a file comment describing what the file is for and any other descriptions that apply to the whole file. | ||
| + | <code c> | ||
| /*! \file <filename.ext> | /*! \file <filename.ext> | ||
| \brief Put a brief summary of what this file is for... | \brief Put a brief summary of what this file is for... | ||
| Line 31: | Line 31: | ||
| A lengthier description of what the file is for (this is optional). | A lengthier description of what the file is for (this is optional). | ||
| */ | */ | ||
| + | </code> | ||
| ==== Documenting Variables/Defines/Typedefs ==== | ==== Documenting Variables/Defines/Typedefs ==== | ||
| Line 36: | Line 37: | ||
| Global variables in a file can be documented using the **\var** command or by just writing a comment with a **\brief** command right before the definition. | Global variables in a file can be documented using the **\var** command or by just writing a comment with a **\brief** command right before the definition. | ||
| + | <code c> | ||
| /*! \brief fill style of objects like cirle, rect, path */ | /*! \brief fill style of objects like cirle, rect, path */ | ||
| typedef enum {FILLING_HOLLOW, FILLING_FILL, FILLING_MESH, FILLING_HATCH, FILLING_VOID} OBJECT_FILLING; | typedef enum {FILLING_HOLLOW, FILLING_FILL, FILLING_MESH, FILLING_HATCH, FILLING_VOID} OBJECT_FILLING; | ||
| + | </code> | ||
| ==== Documenting Functions ==== | ==== Documenting Functions ==== | ||
| Line 47: | Line 50: | ||
| Also **\param** commands are used with the [in] or [out] attributes to document if the parameter will be modified by the function. | Also **\param** commands are used with the [in] or [out] attributes to document if the parameter will be modified by the function. | ||
| + | <code c> | ||
| /*! \brief "Save" a file into a string buffer | /*! \brief "Save" a file into a string buffer | ||
| * \par Function Description | * \par Function Description | ||
| Line 56: | Line 60: | ||
| * \return a buffer containing schematic data or NULL on failure. | * \return a buffer containing schematic data or NULL on failure. | ||
| */ | */ | ||
| + | </code> | ||
| ==== Structure Documentation ==== | ==== Structure Documentation ==== | ||
| - | Structures are documented the same as in the previous sections. Note that comments on the structure members can be documented inline or using the same **\brief** syntax as variables. Inline documentation requires the special comment starting with **/*!<** at the end of the line it applies to. | + | Structures are documented the same as in the previous sections. Note that comments on the structure members can be documented inline or using the same **\brief** syntax as variables. Inline documentation requires the special comment starting with **%%/*!<%%** at the end of the line it applies to. |
| + | <code c> | ||
| /*! \brief Structure for connections between OBJECTs | /*! \brief Structure for connections between OBJECTs | ||
| * | * | ||
| Line 77: | Line 83: | ||
| int other_whichone; /*!< which endpoint of the "other" object caused this connection */ | int other_whichone; /*!< which endpoint of the "other" object caused this connection */ | ||
| }; | }; | ||
| + | </code> | ||
| Line 395: | Line 402: | ||
| ==Hotkeys== | ==Hotkeys== | ||
| - | * | + | * |
geda/devel-tips.txt · Last modified: 2014/04/18 11:25 by vzh
Page Tools
Except where otherwise noted, content on this wiki is licensed under the following license: CC Attribution-Share Alike 4.0 International
