Linduino  1.3.0
Linear Technology Arduino-Compatible Demonstration Board
DoxygenReference.md
Go to the documentation of this file.
1 
2 Doxygen Reference
3 ==================
4 
5 Linduino documentation is automatically generated from the source code using
6 Doxygen. Refer to the following templates when documenting code.
7 
8 \b %DoxygenExample.ino:
9 
10 [Source Code](file:./DoxygenExample_8cpp_source.html "Source Code")
11 
12 [Doxygen Generated Output](file:./DoxygenExample_8cpp.html "Doxygen Generated Output")
13 
14 \b %DoxygenExample.h:
15 
16 [Source Code](file:./DoxygenExample_8h_source.html "Source Code")
17 
18 [Doxygen Generated Output](file:./DoxygenExample_8h.html "Doxygen Generated Output")
19 
20 \b %DoxygenExample.cpp:
21 
22 [Source Code](file:./DoxygenExample_8cpp_source.html "Source Code")
23 
24 [Doxygen Generated Output](file:./DoxygenExample_8cpp.html "Doxygen Generated Output")
25 
26 Store the .ino file in a folder with the same name (i.e. "DoxygenDemo.ino" is
27 stored in a folder named "DoxygenDemo"). The folder may be stored in
28 LTSketchbook or in any folder not labeled as Libraries.
29 
30 If the .h and .cpp files will only be used by one .ino program, store them in the
31 same folder with the .ino file. For example, "DoxygenExample.cpp" and
32 "DoxygenExample.h" are stored in the "DoxygenDemo" folder. Alternatively, if the
33 files form a library to be used by other .ino files, store the "DoxygenExample.h"
34 and "DoxygenExample.cpp" files in the Libararies folder of the LTSketchbook.
35 
36 Documenting the .ino
37 --------------------
38 <b>The .ino file must include the following lines, where "groupname" is replaced by a
39 descriptive name used to group the .ino, .cpp, and .h files.</b>
40 
41 @verbatim
42 
43 /*! @file
44  @ingroup groupname
45 */
46 @endverbatim
47 
48 Documenting a function with parameters and no return:
49 
50 @verbatim
51 
52 //! Message that describes the function
53 //! @return void
54 void function1(int param1, //!< Message that describes the function of the variable
55  float param2, //!< Message that describes the function of the variable
56  char param3 //!< Message that describes the function of the variable
57  )
58 {
59 }
60 
61 @endverbatim
62 Click \ref function1() "here" to see the output.
63 
64 Documenting a function with no parameters and a return:
65 
66 @verbatim
67 
68 //! Message that describes the function
69 //! @return Describe the return conditions
70 float function2()
71 {
72 }
73 @endverbatim
74 Click \ref function2() "here" to see the output.
75 
76 
77 Documenting for the C++ and Header File
78 ------------------------------------------
79 <b>The header file (*.h) must include the following lines, where "groupname" is
80 replaced by a descriptive name used to group the .ino, .cpp, and .h files.</b>
81 
82 @verbatim
83 
84 /*! @file
85  @ingroup groupname
86  Header for Description_of_the_header
87 */
88 
89 @endverbatim
90 
91 <b>The C++ file (*.cpp) must include the following lines, where "groupname" is replaced by a
92 descriptive name used to group the .ino, .cpp, and .h files. "categoryname" is replaced by one
93 of the categories shown the table below. </b>
94 
95 @verbatim
96 
97 /*! @file
98  @ingroup categoryname
99  @{
100  @defgroup groupname Doxygen Documentation Example
101  @}
102  @ingroup groupname
103  Library for Description_of_the_header
104 */
105 
106 @endverbatim
107 
108 categoryname | Description
109 ---------------------------- | -------------------------------------------------------------------------------------
110 Linduino | Linduino: Linear Technology Arduino-Compatible Demonstration Board Support Libraries
111 Analog_to_Digital_Converters | Analog-to-Digital Converters (ADC)
112 Digital_to_Analog_Converters | Digital-to-Analog Converters (DAC)
113 Hot_Swap | Hot Swap
114 Power_Monitors | Power Monitors and Coulomb Counters
115 Power_System_Management | Digital Power System Management and Power Supply Supervisors
116 Switching_Regulators | Switching Regulators, Battery Chargers, and LED Drivers
117 Transceivers | Transceivers
118 Temperature_Monitors | Temperature Monitors
119 RF_Timing | RF, Silicon Oscillators, PLL Synthesizers, and VCOs
120 BMS | Battery Management System (BMS)
121 PMBus_SMBus | PMBus and SMBus Support Libraries
122 Example_Designs | Example Designs
123 User_Contributed | User Contributed Libraries (Not Supported by Linear Technology)
124 Third_Party | Third-Party Libraries (Not Supported by Linear Technology)
125 Documentation | Documentation
126 WIP | Work in Progress
127 
128 <b>It is recommended that the Doxygen documentation for functions be placed in the
129 header file (*.h) and not the C++ file (*.cpp).</b>
130 
131 Documenting a function with no parameters and no return:
132 
133 @verbatim
134 
135 //! Message that describes the main function
136 //! @return void
137 void function3();
138 
139 @endverbatim
140 Click \ref function3() "here" to see the output.
141 
142 Documenting a function with parameters and a return:
143 
144 @verbatim
145 
146 //! Message that describes the main function
147 //! @return Describe the return conditions
148 int function4(int var1, //!< Message that describes the function of the variable
149  float var2 //!< Message that describes the function of the variable
150  );
151 
152 @endverbatim
153 Click \ref function3() "here" to see the output.
154 
155 <b> Note: If the comment that describes the variable is placed after the semicolon, Doxygen
156 will not document the last variable. Be sure to comment the variables before the semicolon.</b>
157 
158 Documenting Global Variables, Constants, Defines, and Enum
159 ----------------------------------------------------
160 
161 @verbatim
162 static float float_var; //!< Message that describes the function of the variable
163 const int int_var; //!< Message that describes the function of the constant variable
164 #define var //!< Message that describes the function of the define
165 
166 //! Enum Description
167 enum EnumType
168  {
169  int EVal1, /**< enum value 1 */
170  int EVal2 /**< enum value 2 */
171  };
172 @endverbatim
173 
174 Adding a Title
175 ---------------
176 @verbatim
177 /*! @name TITLE
178 @{
179  The section that receives the title.
180 @}
181 */
182 @endverbatim
183 
184 Making Tables
185 -------------
186 
187 @verbatim
188 First Header | Second Header
189 ------------- | -------------
190 Content Cell | Content Cell
191 Content Cell | Content Cell
192 @endverbatim
193 
194 First Header | Second Header
195 ------------- | -------------
196 Content Cell | Content Cell
197 Content Cell | Content Cell
198 
199 Column alignment can be controlled via one or two colons at the header separator line:
200 
201 @verbatim
202 | Right | Center | Left |
203 | ----: | :----: | :---- |
204 | 10 | 10 | 10 |
205 | 1000 | 1000 | 1000 |
206 @endverbatim
207 
208 
209 | Right | Center | Left |
210 | ----: | :----: | :---- |
211 | 10 | 10 | 10 |
212 | 1000 | 1000 | 1000 |
213 
214 Making Lists
215 ------------
216 @verbatim
217 - Item 1
218 
219  More text for this item.
220 
221 - Item 2
222  + nested list item.
223  + another nested item.
224 - Item 3
225 @endverbatim
226 
227 - Item 1
228 
229  More text for this item.
230 
231 - Item 2
232  + nested list item.
233  + another nested item.
234 - Item 3
235 
236 Links
237 ------
238 @verbatim
239 [The link text](http://www.linear.com/ "Link title")
240 @endverbatim
241 [The link text](http://www.linear.com/ "Link title")
242 
243 Images
244 -------
245 @verbatim
246 ![Caption text](/path/to/img.jpg "Image title")
247 @endverbatim
248 
249 Emphasis
250 ---------
251 @verbatim
252 _single underscores_
253 @endverbatim
254 _single underscores_
255 
256 Bold
257 -----
258 @verbatim
259 
260 \b word
261 
262 <b> more than one word </b>
263 
264 @endverbatim
265 \b word
266 
267 <b> more than one word </b>
268 
269 Adding a bug to the bug list
270 --------------------------------
271 Add the following comment above the function with the bug
272 @verbatim
273 
274 //! @bug bug description
275 
276 @endverbatim
277 
278 More Information
279 ----------------
280 For more information please refer to the Doxygen manual in the [Doxygen website](http://www.doxygen.org/ "Doxygen")
281 
282 @defgroup Linduino Linduino: Linear Technology Arduino-Compatible Demonstration Board Support Libraries
283 @defgroup Analog_to_Digital_Converters Analog-to-Digital Converters (ADC)
284 @defgroup Digital_to_Analog_Converters Digital-to-Analog Converters (DAC)
285 @defgroup Hot_Swap Hot Swap
286 @defgroup Power_Monitors Power Monitors and Coulomb Counters
287 @defgroup Power_System_Management Digital Power System Management and Power Supply Supervisors
288 @defgroup Switching_Regulators Switching Regulators, Battery Chargers, and LED Drivers
289 @defgroup Transceivers Transceivers
290 @defgroup Temperature_Monitors Temperature Monitors
291 @defgroup RF_Timing RF, Silicon Oscillators, PLL Synthesizers, and VCOs
292 @defgroup BMS Battery Management System (BMS)
293 @defgroup PMBus_SMBus PMBus and SMBus Support Libraries
294 @defgroup Example_Designs Example Designs
295 @defgroup User_Contributed User Contributed Libraries (Not Supported by Linear Technology)
296 @defgroup Third_Party Third-Party Libraries (Not Supported by Linear Technology)
297 @defgroup Documentation Documentation
298 @defgroup WIP Work in Progress