Changes between Version 5 and Version 6 of HeaderDoc
- Timestamp:
- Nov 5, 2009, 6:15:18 AM (14 years ago)
Legend:
- Unmodified
- Added
- Removed
- Modified
-
HeaderDoc
v5 v6 24 24 $ make doc 25 25 }}} 26 27 Please '''have a look to warning messages'''. Most {{{Undefined type}}} messages are ok but other messages may indicate real issues.28 26 29 27 == Adding files and modules == … … 58 56 59 57 %config CONFIG_MY_OPTION 60 desc Please try to write a really useful descr ption here from now !!!58 desc Please try to write a really useful description here from now !!! 61 59 %config end 62 60 }}} 63 61 64 62 = Writing documentation in headers = 63 64 ---- 65 66 == The rules == 67 68 {{{ 69 #!html 70 <span style="text-align: center; color: #ff0000; font-size: 150%;">It's really important to follow these basic rules when writing the documentation. Not following these rules carefully would make your documentation useless, as reading the source code directly will be more attracting !!!</span> 71 }}} 72 73 Here are the rules: 74 75 * Please always '''make complete sentences''' starting with '''C'''apitals. (It would be great to apply this to configuration tokens description too). 76 * Do not make sentences for short description of files and modules introduced by a {{{@short}}} tag. 77 * Do not forget to '''insert reference tags''' for each identifier and macro name, so that !MkDoc can generate an hyperlink. Not having a direct link is really frustrating for the reader. 78 * Remember that you can not count on other declarations proximity to make things obvious, contiguous things in the header '''may not be contiguous in the document'''. 79 * Try to '''mark all internal declarations as such''', this will help sorting list with relevant items first, using the right style, and make things clear. 80 * Remember you are not writing plain documentation but only small piece of sentences inserted in a large document. 81 * Consider the '''warning messages''' from !MkDoc and '''read carefully the output document''' to double check previous rules and see if everything is easily understandable and make sens. 82 83 ---- 65 84 66 85 == Comments format == … … 76 95 }}} 77 96 78 Please always '''make complete sentences''' starting with '''C'''apitals. The {{{@this}}} tag can be used as a shortcut which is replaced by something like "''This static function''", "''This variable''" ... It would be great to apply this to configuration tokens description too. Note this advice '''does not apply to short description''' of files and modules introduced by a {{{@short}}} tag which must be brief. 97 The {{{@this}}} tag can be used as a shortcut which is replaced by something like "''This static function''", "''This variable''" ... 79 98 80 99 {{{ … … 103 122 * {{{@hidden}}}: This tag must be used to hide something you really don't want to appear in the documentation. Note that '''preprocessor macros are hidden by default''' if not commented. 104 123 * {{{@multiple}}}: This tag can be used to apply the same documentation more than once, up to the next documentation comment. 105 * {{{@param}}} and {{{@return}}}: These tags can be used to document parameters and return values. Please '''don't use it for all functions''' if the information are obvious. The {{{@return}}} tag starts a sentence like "''The return value is''". The {{{@param}}} tag adds a "''Parameters list:''" if at the beginning of a paragraph. 124 * {{{@param}}} and {{{@return}}}: These tags can be used to document parameters and return values. Please '''don't use it for all functions''' if the information are obvious. The {{{@return}}} tag starts a sentence like "''The return value is''". The {{{@param}}} tag adds a "''Parameters list:''" if at the beginning of a paragraph. Do not forget to insert an empty line when beginning a normal text paragraph after these tags. 106 125 * {{{@showcontent}}}: This tag can be used to make the content of a preprocessor macro and numerical values of enums visible in the documentation. 107 126 * {{{@ref}}} and {{{@see}}}: These tags may be used when refering to an other symbol. The {{{@ref}}} tag just insert a link to the specified symbol where it appears. {{{@see}}} tags automatically generate a nice sentence add the symbol documentation end pointing to all related symbols. Do not forget to '''prepend a sharp (#) sign to macro names''' as they are in a different name space to avoid collisions. Headers and modules can be refered too with @ and + sign prefix. … … 140 159 Many other tags can be used to format text, insert examples, write structured plain documentation... Please refer to the [http://www.nongnu.org/mkdoc/ MkDoc manual] '''for detailled syntax and usage''' of discussed tags and list of other cool tags. 141 160 142 = = What goes in the generated doc ==161 = What goes in the generated doc = 143 162 144 163 * Its embedded preprocessor enables !MkDoc to '''expose declarations which take place in macro expansion''' with information about involved header files, macros and exact line positions. Please '''do not comment things twice''' when repeated but enclosed in a {{{#if #else #endif}}} as this is useless unless you want to show different macro contents for instance. … … 148 167 . 149 168 150 = = Generated output ==169 = Generated output = 151 170 152 171 The default is to generate html documentation in {{{doc/html}}}, but tweaks and other formats are available as described in !MkDoc manual. You may for instance generate a latex source file:
