forked from Gnucash/gnucash
-
Notifications
You must be signed in to change notification settings - Fork 0
/
doxygen_main_page.c
201 lines (144 loc) · 6.74 KB
/
doxygen_main_page.c
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
/** \mainpage GnuCash design and developer's reference
This is the new developer and design manual for GnuCash.
\section maindocs Documentation Sections
The documentation is organised in a rough sequence:
-# \ref manualguide Start with the main GnuCash manual.
-# \ref highlevel Pages that cover topics at a higher level. Most also have
links to the full API reference they relate to.
-# \ref maingeneral How to work with Doxygen in your own code.
\section manualguide External documentation
Please refer to the main
<a href="https://www.gnucash.org/docs.phtml">documentation
page</a> on the gnucash website which includes links to the
GnuCash Manual and the Concepts Guide in various formats.
\section highlevel Highlevel overviews
Pages that cover topics at a higher level. Most also have
links to the full API reference they relate to.
- \ref deprecated
- \ref loanhandling
- \ref kvpvalues
- \ref lotsoverview
- \ref python_bindings_page
- \ref todo
\section maingeneral General Doxygen help
- \ref tipshints
- \ref reference
*/
/********************************************************************\
* This program is free software; you can redistribute it and/or *
* modify it under the terms of the GNU General Public License as *
* published by the Free Software Foundation; either version 2 of *
* the License, or (at your option) any later version. *
* *
* This program is distributed in the hope that it will be useful, *
* but WITHOUT ANY WARRANTY; without even the implied warranty of *
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the *
* GNU General Public License for more details. *
* *
* You should have received a copy of the GNU General Public License*
* along with this program; if not, contact: *
* *
* Free Software Foundation Voice: +1-617-542-5942 *
* 51 Franklin Street, Fifth Floor Fax: +1-617-542-2652 *
* Boston, MA 02110-1301, USA [email protected] *
* *
\********************************************************************/
/* Editing this file? Comments can be inserted in this file
Remember to use C syntax but skip the extra asterisk so that doxygen
ignores the extra notes, like this one.
*/
/* Hacking alert: When adding new sections, keep the references in
alphabetical order OF THE DESCRIPTION, not the reference title.
Also, make sure all reference titles are unique across the entire
Doxygen output.
Keep each section within one C comment block and any text before
the first section of a page must be in the same comment block as the
page title itself.
*/
/** \section hacking Hacking on this documentation
There is the beginning of a style guide for documenting under
\ref tipshints
Feel free to start documenting or playing with doxygen configuration.
This main page can be found in src/doc/doxygen_main_page.c .
This main page is just an introduction to doxygen markup, see the
Doxygen manual for the full command set.
- \ref tipshints Tips and hints for using doxygen
- \ref reference Links to the Doxygen manual
Code snippets need special handling in the text overviews. Change all
comment markers to // (so that the overview comment remains intact)
and then wrap each code snippet in the \a verbatim \a endverbatim
doxygen markers.
One useful method is to edit these .txt files using the syntax highlighting
of normal C files.
*/
/**
\page tipshints Useful tips for doxygen in C files
- \ref index Introduction
- \ref reference The Doxygen manual
\section tips An introduction to doxygen markup
\subsection Locations What to document
All declarations for:
-# typedef
-# struct
-# enum
-# functions
This will enable doxygen to link all parameter types to the declarations
every time the type is used in a function - very helpful to new developers.
\subsection Files Private files
If your declarations are in separate files, like private header files,
a simple block can still be linked into doxygen as long as the file is
identified to doxygen using a '\\file' section:
** \\file filename.h\n
\\brief one-liner summary of the file purpose\n
\\author the usual copyright statement
\subsection Methods How to document
Every doxygen comment block starts with an adapted comment marker.
You can use an extra slash /// or an extra asterisk ** . Blocks end
in the usual way. Doxygen accepts commands using a backslash.
To put a description with each function or structure, use '\\brief'
End the brief description with a blank line. The rest of the documentation will
then be shown in the body of the doxygen page.
Commands may begin with \\ or @
\subsection Presentation Extras
-# Start a line with a hyphen to start a list - the indent determines the
nesting of the list:
- To create a numbered list, use -# e.g. for a sublist:
-# start a numbered list
- revert to previous list
End the list with a blank line.
Use :: at the start of a function or structure to link to the page
for that function in the doxygen documentation. e.g. ::qof_class_foreach
Use the param command to describe function parameters in the text.
Use the 'back reference' to document enumerator values:\n
enum testenum {\n
enum_one **< less than marker tells doxygen to use this line
to document enum_one.
\subsection config Editing Doxygen configuration
To edit the doxygen configuration, you can use:
*
cd src/doc
*
doxywizard doxygen.cfg &
*/
/** \page reference Doxygen reference documentation
- \ref index Introduction
- \ref tipshints Tips and hints for using doxygen
The Doxygen web site (https://www.stack.nl/~dimitri/doxygen/ [DEAD LINK]) has a
complete user manual. For the impatient, here are the most
interesting sections:
- How to write grouped documentation for files, functions, variables,
etc.: https://www.stack.nl/~dimitri/doxygen/grouping.html [DEAD LINK] . Do not
forget to add a file documentation block (\@file) at the top of your
file. Otherwise, all documentation in that file will <i>not</i> appear
in the html output.
- List of the special commands you can use within your documentation
blocks: https://www.stack.nl/~dimitri/doxygen/commands.html [DEAD LINK]
\section contact Contacts
\subsection web Web Site
News about GnuCash as well as the latest version can always be found at https://www.gnucash.org/
\subsection email Email
If you have any suggestions concerning this documentation, do not hesitate to send suggestions to
gnucash-devel (see https://www.gnucash.org/en/lists.phtml for details)
Benoit Grégoire <[email protected]>
Neil Williams <[email protected]>
*/