Debian Codegraph @

geanygendoc/docs/manual.html

raw
1 <?xml version="1.0" encoding="utf-8" ?>
2 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
3 <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
4 <head>
5 <meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
6 <meta name="generator" content="Docutils 0.12: http://docutils.sourceforge.net/" />
7 <title>GeanyGenDoc User Manual</title>
8 <style type="text/css">
9
10 /*
11 :Author: David Goodger ([email protected])
12 :Id: $Id: html4css1.css 7056 2011-06-17 10:50:48Z milde $
13 :Copyright: This stylesheet has been placed in the public domain.
14
15 Default cascading style sheet for the HTML output of Docutils.
16
17 See http://docutils.sf.net/docs/howto/html-stylesheets.html for how to
18 customize this style sheet.
19 */
20
21 /* used to remove borders from tables and images */
22 .borderless, table.borderless td, table.borderless th {
23 border: 0 }
24
25 table.borderless td, table.borderless th {
26 /* Override padding for "table.docutils td" with "! important".
27 The right padding separates the table cells. */
28 padding: 0 0.5em 0 0 ! important }
29
30 .first {
31 /* Override more specific margin styles with "! important". */
32 margin-top: 0 ! important }
33
34 .last, .with-subtitle {
35 margin-bottom: 0 ! important }
36
37 .hidden {
38 display: none }
39
40 a.toc-backref {
41 text-decoration: none ;
42 color: black }
43
44 blockquote.epigraph {
45 margin: 2em 5em ; }
46
47 dl.docutils dd {
48 margin-bottom: 0.5em }
49
50 object[type="image/svg+xml"], object[type="application/x-shockwave-flash"] {
51 overflow: hidden;
52 }
53
54 /* Uncomment (and remove this text!) to get bold-faced definition list terms
55 dl.docutils dt {
56 font-weight: bold }
57 */
58
59 div.abstract {
60 margin: 2em 5em }
61
62 div.abstract p.topic-title {
63 font-weight: bold ;
64 text-align: center }
65
66 div.admonition, div.attention, div.caution, div.danger, div.error,
67 div.hint, div.important, div.note, div.tip, div.warning {
68 margin: 2em ;
69 border: medium outset ;
70 padding: 1em }
71
72 div.admonition p.admonition-title, div.hint p.admonition-title,
73 div.important p.admonition-title, div.note p.admonition-title,
74 div.tip p.admonition-title {
75 font-weight: bold ;
76 font-family: sans-serif }
77
78 div.attention p.admonition-title, div.caution p.admonition-title,
79 div.danger p.admonition-title, div.error p.admonition-title,
80 div.warning p.admonition-title {
81 color: red ;
82 font-weight: bold ;
83 font-family: sans-serif }
84
85 /* Uncomment (and remove this text!) to get reduced vertical space in
86 compound paragraphs.
87 div.compound .compound-first, div.compound .compound-middle {
88 margin-bottom: 0.5em }
89
90 div.compound .compound-last, div.compound .compound-middle {
91 margin-top: 0.5em }
92 */
93
94 div.dedication {
95 margin: 2em 5em ;
96 text-align: center ;
97 font-style: italic }
98
99 div.dedication p.topic-title {
100 font-weight: bold ;
101 font-style: normal }
102
103 div.figure {
104 margin-left: 2em ;
105 margin-right: 2em }
106
107 div.footer, div.header {
108 clear: both;
109 font-size: smaller }
110
111 div.line-block {
112 display: block ;
113 margin-top: 1em ;
114 margin-bottom: 1em }
115
116 div.line-block div.line-block {
117 margin-top: 0 ;
118 margin-bottom: 0 ;
119 margin-left: 1.5em }
120
121 div.sidebar {
122 margin: 0 0 0.5em 1em ;
123 border: medium outset ;
124 padding: 1em ;
125 background-color: #ffffee ;
126 width: 40% ;
127 float: right ;
128 clear: right }
129
130 div.sidebar p.rubric {
131 font-family: sans-serif ;
132 font-size: medium }
133
134 div.system-messages {
135 margin: 5em }
136
137 div.system-messages h1 {
138 color: red }
139
140 div.system-message {
141 border: medium outset ;
142 padding: 1em }
143
144 div.system-message p.system-message-title {
145 color: red ;
146 font-weight: bold }
147
148 div.topic {
149 margin: 2em }
150
151 h1.section-subtitle, h2.section-subtitle, h3.section-subtitle,
152 h4.section-subtitle, h5.section-subtitle, h6.section-subtitle {
153 margin-top: 0.4em }
154
155 h1.title {
156 text-align: center }
157
158 h2.subtitle {
159 text-align: center }
160
161 hr.docutils {
162 width: 75% }
163
164 img.align-left, .figure.align-left, object.align-left {
165 clear: left ;
166 float: left ;
167 margin-right: 1em }
168
169 img.align-right, .figure.align-right, object.align-right {
170 clear: right ;
171 float: right ;
172 margin-left: 1em }
173
174 img.align-center, .figure.align-center, object.align-center {
175 display: block;
176 margin-left: auto;
177 margin-right: auto;
178 }
179
180 .align-left {
181 text-align: left }
182
183 .align-center {
184 clear: both ;
185 text-align: center }
186
187 .align-right {
188 text-align: right }
189
190 /* reset inner alignment in figures */
191 div.align-right {
192 text-align: inherit }
193
194 /* div.align-center * { */
195 /* text-align: left } */
196
197 ol.simple, ul.simple {
198 margin-bottom: 1em }
199
200 ol.arabic {
201 list-style: decimal }
202
203 ol.loweralpha {
204 list-style: lower-alpha }
205
206 ol.upperalpha {
207 list-style: upper-alpha }
208
209 ol.lowerroman {
210 list-style: lower-roman }
211
212 ol.upperroman {
213 list-style: upper-roman }
214
215 p.attribution {
216 text-align: right ;
217 margin-left: 50% }
218
219 p.caption {
220 font-style: italic }
221
222 p.credits {
223 font-style: italic ;
224 font-size: smaller }
225
226 p.label {
227 white-space: nowrap }
228
229 p.rubric {
230 font-weight: bold ;
231 font-size: larger ;
232 color: maroon ;
233 text-align: center }
234
235 p.sidebar-title {
236 font-family: sans-serif ;
237 font-weight: bold ;
238 font-size: larger }
239
240 p.sidebar-subtitle {
241 font-family: sans-serif ;
242 font-weight: bold }
243
244 p.topic-title {
245 font-weight: bold }
246
247 pre.address {
248 margin-bottom: 0 ;
249 margin-top: 0 ;
250 font: inherit }
251
252 pre.literal-block, pre.doctest-block, pre.math {
253 margin-left: 2em ;
254 margin-right: 2em }
255
256 span.classifier {
257 font-family: sans-serif ;
258 font-style: oblique }
259
260 span.classifier-delimiter {
261 font-family: sans-serif ;
262 font-weight: bold }
263
264 span.interpreted {
265 font-family: sans-serif }
266
267 span.option {
268 white-space: nowrap }
269
270 span.pre {
271 white-space: pre }
272
273 span.problematic {
274 color: red }
275
276 span.section-subtitle {
277 /* font-size relative to parent (h1..h6 element) */
278 font-size: 80% }
279
280 table.citation {
281 border-left: solid 1px gray;
282 margin-left: 1px }
283
284 table.docinfo {
285 margin: 2em 4em }
286
287 table.docutils {
288 margin-top: 0.5em ;
289 margin-bottom: 0.5em }
290
291 table.footnote {
292 border-left: solid 1px black;
293 margin-left: 1px }
294
295 table.docutils td, table.docutils th,
296 table.docinfo td, table.docinfo th {
297 padding-left: 0.5em ;
298 padding-right: 0.5em ;
299 vertical-align: top }
300
301 table.docutils th.field-name, table.docinfo th.docinfo-name {
302 font-weight: bold ;
303 text-align: left ;
304 white-space: nowrap ;
305 padding-left: 0 }
306
307 h1 tt.docutils, h2 tt.docutils, h3 tt.docutils,
308 h4 tt.docutils, h5 tt.docutils, h6 tt.docutils {
309 font-size: 100% }
310
311 ul.auto-toc {
312 list-style-type: none }
313
314 </style>
315 <style type="text/css">
316
317 /*
318 :Author: Colomban Wendling
319 :Contact: [email protected]
320 :Copyright: This stylesheet has been placed in the public domain.
321
322 Stylesheet for use with Docutils.
323 */
324
325 /*@import url(html4css1.css);*/
326
327 html {
328 background-color: #eeeeec;
329 color: #2e3436;
330 font-family: bitstream vera sans, sans-serif;
331 margin: 0 1em;
332 }
333
334
335 h1, h2, h3, h4, h5, h6, p.topic-title {
336 font-family: georgia, times new roman, times, serif;
337 }
338
339 h2.subtitle {
340 font-style: italic;
341 font-weight: normal;
342 }
343
344 p, dd {
345 text-align: justify;
346 }
347
348 blockquote {
349 padding-left: 1em;
350 margin-left: 1em;
351 border-left: 3px solid #5c3566;
352 }
353
354 .literal-block,
355 .literal {
356 background: #fff;
357 }
358 .literal-block {
359 border: 1px solid #babdb6;
360 padding: 1px 2px;
361 }
362 h1 .literal, h2 .literal, h3 .literal, h4 .literal, h5 .literal, h6 .literal
363 p.topic-title .literal {
364 background: inherit;
365 text-align: left;
366 }
367
368
369 .footnote-reference {
370 vertical-align: super;
371 font-size: 75%;
372 }
373
374
375 a { text-decoration: none; }
376 a:hover { text-decoration: underline }
377 a:link { color: #204a87; }
378 a:visited { color: #5c3566; }
379
380 h1 a, h1 a:hover, h1 a:link, h1 a:visited,
381 h2 a, h2 a:hover, h2 a:link, h2 a:visited,
382 h3 a, h3 a:hover, h3 a:link, h3 a:visited,
383 h4 a, h4 a:hover, h4 a:link, h4 a:visited,
384 h5 a, h5 a:hover, h5 a:link, h5 a:visited,
385 h6 a, h6 a:hover, h6 a:link, h6 a:visited,
386 p.topic-title a, p.topic-title a:hover, p.topic-title a:link, p.topic-title a:visited
387 {
388 text-decoration: none;
389 color: inherit;
390 }
391
392 </style>
393 </head>
394 <body>
395 <div class="document" id="geanygendoc-user-manual">
396 <h1 class="title">GeanyGenDoc User Manual</h1>
397 <h2 class="subtitle" id="a-handy-hand-guide-for-the-lazy-documenter-in-you">A handy hand guide for the lazy documenter in you</h2>
398
399 <div class="section" id="introduction">
400 <h1><a class="toc-backref" href="#id4">Introduction</a></h1>
401 <p>First of all, welcome to this manual. Then, what is GeanyGenDoc? It is a
402 plug-in for Geany as you might have noticed; but what is it meant to do?
403 Basically, it generates and inserts text chunks, particularly from document's
404 symbols. Its goal is to ease writing documentation for the good.</p>
405 <p>If you are impatient, you will probably want to discover the <a class="reference internal" href="#user-interface-in-geany">user interface in
406 Geany</a> first; but if you have the time to discover the tool, take a look at the
407 <a class="reference internal" href="#design">design</a> and learn how GeanyGenDoc works and how you can make the most of it.</p>
408 <div class="contents topic" id="contents">
409 <p class="topic-title first">Contents</p>
410 <ul class="simple">
411 <li><a class="reference internal" href="#introduction" id="id4">Introduction</a></li>
412 <li><a class="reference internal" href="#user-interface-in-geany" id="id5">User interface in Geany</a><ul>
413 <li><a class="reference internal" href="#menus" id="id6">Menus</a><ul>
414 <li><a class="reference internal" href="#editor-s-pop-up-menu" id="id7">Editor's pop-up menu</a></li>
415 <li><a class="reference internal" href="#tools-menu" id="id8">Tools menu</a></li>
416 </ul>
417 </li>
418 <li><a class="reference internal" href="#preferences-dialog" id="id9">Preferences dialog</a></li>
419 </ul>
420 </li>
421 <li><a class="reference internal" href="#design" id="id10">Design</a></li>
422 <li><a class="reference internal" href="#syntax" id="id11">Syntax</a><ul>
423 <li><a class="reference internal" href="#key-value-pairs" id="id12">Key-Value pairs</a></li>
424 <li><a class="reference internal" href="#naming" id="id13">Naming</a></li>
425 <li><a class="reference internal" href="#comments" id="id14">Comments</a></li>
426 <li><a class="reference internal" href="#value-types" id="id15">Value types</a></li>
427 </ul>
428 </li>
429 <li><a class="reference internal" href="#file-types" id="id16">File types</a><ul>
430 <li><a class="reference internal" href="#the-settings-group" id="id17">The <tt class="docutils literal">settings</tt> group</a></li>
431 <li><a class="reference internal" href="#the-doctypes-group" id="id18">The <tt class="docutils literal">doctypes</tt> group</a></li>
432 </ul>
433 </li>
434 <li><a class="reference internal" href="#documentation-types" id="id19">Documentation types</a><ul>
435 <li><a class="reference internal" href="#short-example" id="id20">Short example</a></li>
436 </ul>
437 </li>
438 <li><a class="reference internal" href="#rules-the-cool-thing" id="id21">Rules: the cool thing</a><ul>
439 <li><a class="reference internal" href="#type-hierarchy" id="id22">Type hierarchy</a><ul>
440 <li><a class="reference internal" href="#known-types" id="id23">Known types</a></li>
441 </ul>
442 </li>
443 <li><a class="reference internal" href="#rule-settings" id="id24">Rule settings</a></li>
444 </ul>
445 </li>
446 <li><a class="reference internal" href="#miscellaneous" id="id25">Miscellaneous</a><ul>
447 <li><a class="reference internal" href="#configuration-directories" id="id26">Configuration directories</a></li>
448 </ul>
449 </li>
450 <li><a class="reference internal" href="#appendix" id="id27">Appendix</a><ul>
451 <li><a class="reference internal" href="#license" id="id28">License</a></li>
452 <li><a class="reference internal" href="#configuration-syntax-summary" id="id29">Configuration syntax summary</a></li>
453 </ul>
454 </li>
455 </ul>
456 </div>
457 </div>
458 <div class="section" id="user-interface-in-geany">
459 <h1><a class="toc-backref" href="#id5">User interface in Geany</a></h1>
460 <div class="section" id="menus">
461 <h2><a class="toc-backref" href="#id6">Menus</a></h2>
462 <p>GeanyGenDoc adds an item named <cite>Insert Documentation Comment</cite> in the editor's
463 pop-up under the <cite>Insert Comments</cite> sub-menu; and a menu named
464 <cite>Documentation Generator</cite> into the <cite>Tools</cite> menu.</p>
465 <div class="section" id="editor-s-pop-up-menu">
466 <h3><a class="toc-backref" href="#id7">Editor's pop-up menu</a></h3>
467 <p>The item <cite>Editor's pop-up → Insert Comments → Insert Documentation Comment</cite>
468 generates documentation for the current symbol. It has a keyboard shortcut
469 that can be configured through Geany's keybinding configuration system, under
470 <cite>GeanyGenDoc → Insert Documentation Comment</cite>.</p>
471 </div>
472 <div class="section" id="tools-menu">
473 <h3><a class="toc-backref" href="#id8">Tools menu</a></h3>
474 <p>The <cite>Documentation Generator</cite> menu under <cite>Tools</cite> contains the following items:</p>
475 <dl class="docutils">
476 <dt><cite>Document Current Symbol</cite></dt>
477 <dd>This generates documentation for the current symbol. It is equivalent to the
478 item <cite>Insert Documentation Comment</cite> that can be found in the editor's pop-up
479 menu.</dd>
480 <dt><cite>Document All Symbols</cite></dt>
481 <dd>This generates documentation for all symbols in the document. This is
482 equivalent to manually requesting documentation generation for each symbol in
483 the document.</dd>
484 <dt><cite>Reload Configuration Files</cite></dt>
485 <dd>This force reloading of all the <a class="reference internal" href="#file-types">file type</a> configuration files. It is
486 useful when a file type configuration file was modified, in order to the new
487 configuration to be used without reloading the plugin.</dd>
488 <dt><cite>Edit Current Language Configuration</cite></dt>
489 <dd>This opens the configuration file that applies to the current document for
490 editing. The opened configuration file has write permissions: if it was a
491 system configuration file it is copied under your personal <a class="reference internal" href="#configuration-directories">configuration
492 directory</a> transparently.</dd>
493 <dt><cite>Open Manual</cite></dt>
494 <dd>Opens this manual in a browser.</dd>
495 </dl>
496 </div>
497 </div>
498 <div class="section" id="preferences-dialog">
499 <h2><a class="toc-backref" href="#id9">Preferences dialog</a></h2>
500 <p>The preferences dialog, that can either be opened through <cite>Edit →
501 Plugin Preferences</cite> or with the <cite>Preferences</cite> button in the plugin manager,
502 allows to modify the following preferences:</p>
503 <dl class="docutils">
504 <dt><cite>General</cite></dt>
505 <dd><dl class="first last docutils">
506 <dt><cite>Save file before generating documentation</cite></dt>
507 <dd>Choose whether the current document should be saved to disc before
508 generating the documentation. This is a technical detail, but it is
509 currently needed to have an up-to-date tag list. If you disable this option
510 and ask for documentation generation on a modified document, the behavior
511 may be surprising since the comment will be generated for the last saved
512 state of the document and not the current one.</dd>
513 <dt><cite>Indent inserted documentation</cite></dt>
514 <dd>Chooses whether the inserted documentation should be indented to fit the
515 indentation at the insertion position.</dd>
516 </dl>
517 </dd>
518 <dt><cite>Documentation type</cite></dt>
519 <dd>This list allows you to choose the documentation type to use with each file
520 type. The special language <cite>All</cite> on top of the list is used to choose the
521 default documentation type, used for all languages that haven't one set.</dd>
522 <dt><cite>Global environment</cite></dt>
523 <dd>Global environment overrides and additions. This is an environment that will
524 be merged with the <a class="reference internal" href="#file-types">file type</a>-specific ones, possibly overriding some parts.
525 It can be used to define some values for all the file types, such as whether
526 to write the common <cite>Since</cite> tag, define the <a class="reference external" href="http://www.doxygen.org">Doxygen</a> prefix an so on.
527 Its most practical use case is not to need to change a file type's environment
528 to change the value of one of its elements.</dd>
529 </dl>
530 </div>
531 </div>
532 <div class="section" id="design">
533 <h1><a class="toc-backref" href="#id10">Design</a></h1>
534 <p>GeanyGenDoc has an extensible design based on three points: file type,
535 documentation type and rules.</p>
536 <dl class="docutils">
537 <dt><a class="reference internal" href="#file-types">File type</a></dt>
538 <dd>The file type determines which configuration applies to which document. For
539 example, the &quot;c&quot; file type corresponds to C source, and so on.</dd>
540 <dt><a class="reference internal" href="#documentation-types">Documentation type</a></dt>
541 <dd>A documentation type is an arbitrary name for a set of rules. The goal of
542 documentation types is to allow different set of rules to be defined for each
543 file type.
544 One might want to have separate rules to generate for example <a class="reference external" href="http://www.doxygen.org">Doxygen</a>
545 and <a class="reference external" href="http://www.gtk.org/gtk-doc/">Gtk-Doc</a> documentation from C sources, and should then create two
546 documentation types in the C <a class="reference internal" href="#file-types">file type configuration file</a>, such as
547 &quot;doxygen&quot; and &quot;gtkdoc&quot;.</dd>
548 <dt><a class="reference internal" href="#rules-the-cool-thing">Rule</a></dt>
549 <dd>A rule is a group of settings controlling how a documentation comment is
550 generated. For example, it can define a template, describe how to handle
551 particular imbrications and so on.</dd>
552 </dl>
553 </div>
554 <div class="section" id="syntax">
555 <h1><a class="toc-backref" href="#id11">Syntax</a></h1>
556 <div class="section" id="key-value-pairs">
557 <h2><a class="toc-backref" href="#id12">Key-Value pairs</a></h2>
558 <p>The syntax used by the configuration files is an extended key-value tree
559 definition based on common concepts (trees, string literals, semicolon-ended
560 values, etc.).</p>
561 <p>The key-value syntax is as follows:</p>
562 <pre class="literal-block">
563 key = value
564 </pre>
565 <p>where value is either a semicolon-ended single value:</p>
566 <pre class="literal-block">
567 value;
568 </pre>
569 <p>or a brace-surrounded list of key-value pairs that use the same syntax again:</p>
570 <pre class="literal-block">
571 {
572 key1 = value1
573 key2 = value2
574 }
575 </pre>
576 <p>Here a little example of the <em>syntax</em> (not any actual configuration example):</p>
577 <pre class="literal-block">
578 key1 = value1;
579 key2 = {
580 sub-key1 = sub-value1;
581 sub-key2 = {
582 sub-sub-key1 = sub-sub-value1;
583 }
584 }
585 </pre>
586 </div>
587 <div class="section" id="naming">
588 <h2><a class="toc-backref" href="#id13">Naming</a></h2>
589 <p>Key-value pairs are often referred as <em>group</em> when they are meant to have
590 multiple values and as <em>setting</em> when they have a single value.</p>
591 </div>
592 <div class="section" id="comments">
593 <h2><a class="toc-backref" href="#id14">Comments</a></h2>
594 <p>Is considered as comment (and therefore ignored) everything between a number
595 sign (<tt class="docutils literal">#</tt>) and the following end of line, unless the <tt class="docutils literal">#</tt> occurs as part of
596 another syntactic element (such as a string literal).</p>
597 <p>A short example:</p>
598 <pre class="literal-block">
599 # This is a comment
600 key = value; # This is also a comment
601 string = &quot;A string. # This isn't a comment but a string&quot;;
602 </pre>
603 </div>
604 <div class="section" id="value-types">
605 <h2><a class="toc-backref" href="#id15">Value types</a></h2>
606 <dl class="docutils">
607 <dt>string</dt>
608 <dd><p class="first">A string literal. String literals are surrounded by either single (<tt class="docutils literal">'</tt>) or
609 double (<tt class="docutils literal">&quot;</tt>) quotes.</p>
610 <p>Some special characters can be inserted in a string with an escape sequence:</p>
611 <dl class="docutils">
612 <dt><tt class="docutils literal">\t</tt></dt>
613 <dd>A tabulation.</dd>
614 <dt><tt class="docutils literal">\n</tt></dt>
615 <dd>A new line.</dd>
616 <dt><tt class="docutils literal">\r</tt></dt>
617 <dd>A carriage return.</dd>
618 <dt><tt class="docutils literal">\\</tt></dt>
619 <dd>A backslash.</dd>
620 <dt><tt class="docutils literal">\'</tt></dt>
621 <dd>A single quote (escaping only needed in single-quotes surrounded strings).</dd>
622 <dt><tt class="docutils literal">\&quot;</tt></dt>
623 <dd>A double quote (escaping only needed in double-quotes surrounded strings).</dd>
624 </dl>
625 <p>Note that backslashes are used as the escaping character, which means that it
626 must be escaped to be treated as a simple backslash character.</p>
627 <p>A simple example:</p>
628 <pre class="last literal-block">
629 &quot;This is a string with \&quot;special\&quot; characters.\nThis is another line!&quot;
630 </pre>
631 </dd>
632 <dt>boolean</dt>
633 <dd>A boolean. It can take one of the two symbolic values <tt class="docutils literal">True</tt> and <tt class="docutils literal">False</tt>.</dd>
634 <dt>enumeration</dt>
635 <dd>An enumeration. It consists of a named constant, generally in capital letters.
636 The possible values depend on the setting using this type.</dd>
637 <dt>flags</dt>
638 <dd><p class="first">A logical OR of named constants. This is similar to enumerations but can
639 combine different values.</p>
640 <p class="last">The syntax is common for such types and uses the pipe (<tt class="docutils literal">|</tt>) as
641 combination character. Considering the <tt class="docutils literal">A</tt>, <tt class="docutils literal">B</tt> and <tt class="docutils literal">C</tt> constants, a
642 valid value could be <tt class="docutils literal">A | C</tt>, which represents both <tt class="docutils literal">A</tt> and <tt class="docutils literal">C</tt> but
643 not <tt class="docutils literal">B</tt>.</p>
644 </dd>
645 <dt>list</dt>
646 <dd>A list of values (often referred as array).</dd>
647 </dl>
648 </div>
649 </div>
650 <div class="section" id="file-types">
651 <h1><a class="toc-backref" href="#id16">File types</a></h1>
652 <p>The file type determines which configuration applies to which document.
653 <em>File type identifiers</em> are the lowercased name of Geany's file type, for
654 example &quot;c&quot; or &quot;python&quot;.</p>
655 <p>Configuration for a particular file type goes in a file named
656 <tt class="docutils literal"><span class="pre">file-type-identifier.conf</span></tt> in the <tt class="docutils literal">filetypes</tt> sub-directory of a
657 <a class="reference internal" href="#configuration-directories">configuration directory</a>.</p>
658 <p>A file type configuration can contain two type of things: file-type-wide
659 settings and any number of <a class="reference internal" href="#documentation-types">documentation types</a>.</p>
660 <div class="section" id="the-settings-group">
661 <h2><a class="toc-backref" href="#id17">The <tt class="docutils literal">settings</tt> group</a></h2>
662 <p>This group contains the file-type-wide settings.</p>
663 <dl class="docutils">
664 <dt><tt class="docutils literal">match_function_arguments</tt> (string)</dt>
665 <dd>A regular expression used to extract arguments from a function-style argument
666 list (functions, methods, macros, etc.). This regular expression should match
667 one argument at a time and capture only the argument's name.
668 This setting is a little odd but currently required to extract argument list
669 from function declarations.</dd>
670 <dt><tt class="docutils literal">global_environment</tt> (string)</dt>
671 <dd>A description of a <a class="reference external" href="http://ctpl.tuxfamily.org/">CTPL</a> environment to add when parsing <a class="reference internal" href="#rules-the-cool-thing">rule</a>'s templates.</dd>
672 </dl>
673 </div>
674 <div class="section" id="the-doctypes-group">
675 <h2><a class="toc-backref" href="#id18">The <tt class="docutils literal">doctypes</tt> group</a></h2>
676 <p>This group contains a list of <a class="reference internal" href="#documentation-types">documentation types</a>.</p>
677 </div>
678 </div>
679 <div class="section" id="documentation-types">
680 <h1><a class="toc-backref" href="#id19">Documentation types</a></h1>
681 <p>A documentation type is a named set of <a class="reference internal" href="#rules-the-cool-thing">rules</a> for a <a class="reference internal" href="#file-types">file type</a>, describing how
682 to generate a particular type of documentation (i.e. <a class="reference external" href="http://www.doxygen.org">Doxygen</a>, <a class="reference external" href="http://www.gtk.org/gtk-doc/">Gtk-Doc</a>,
683 <a class="reference external" href="http://www.valadoc.org/">Valadoc</a> or whatever).</p>
684 <p>A documentation type is identified by its name and must therefore be unique
685 in a file type. But of course, different file types can define the same
686 documentation type. It is even recommended for a better consistency to use the
687 same identifier in different file types when they generate the same type of
688 documentation (even though it is completely up to you).</p>
689 <div class="section" id="short-example">
690 <h2><a class="toc-backref" href="#id20">Short example</a></h2>
691 <pre class="literal-block">
692 doxygen = {
693 struct.member = {
694 template = &quot; /**&lt; {cursor} */&quot;;
695 position = AFTER;
696 }
697 struct.template = &quot;/**\n * &#64;brief: {cursor}\n * \n * \n */\n&quot;;
698 }
699 </pre>
700 </div>
701 </div>
702 <div class="section" id="rules-the-cool-thing">
703 <h1><a class="toc-backref" href="#id21">Rules: the cool thing</a></h1>
704 <p>Rules are the actual definition of how documentation is generated. A rule
705 applies to a symbol type and hierarchy, allowing fine control over which and
706 how symbols are documented.</p>
707 <p>A rule is represented as a group of <a class="reference internal" href="#rule-settings">settings</a> in a <a class="reference internal" href="#documentation-types">documentation type</a>.
708 The name of this group is the <a class="reference internal" href="#type-hierarchy">type hierarchy</a> to which the settings applies.</p>
709 <div class="section" id="type-hierarchy">
710 <h2><a class="toc-backref" href="#id22">Type hierarchy</a></h2>
711 <p>A type hierarchy is a hierarchy of the types that a symbol must have to match
712 this rule.</p>
713 <p>In the symbol side, the type hierarchy is the types of the symbol's parents,
714 terminated by the symbol's own type. For example, a method in a class would
715 have a hierarchy like <tt class="docutils literal">class <span class="pre">-&gt;</span> method</tt>; and if the class is itself in a
716 namespace, the hierarchy would the look like <tt class="docutils literal">namespace <span class="pre">-&gt;</span> class <span class="pre">-&gt;</span> method</tt>,
717 and so on.</p>
718 <p>For a rule to apply, its type hierarchy must match <em>the end</em> of the symbol
719 type hierarchy. For example a rule with the type hierarchy <tt class="docutils literal">class</tt> will match
720 a symbol with the type hierarchy <tt class="docutils literal">namespace <span class="pre">-&gt;</span> class</tt> but not one with
721 <tt class="docutils literal">class <span class="pre">-&gt;</span> method</tt>.</p>
722 <p>A type hierarchy uses dots (<tt class="docutils literal">.</tt>) to separate types and build the hierarchy.
723 For example, the type hierarchy representing <tt class="docutils literal">namespace <span class="pre">-&gt;</span> class</tt> would be
724 written <tt class="docutils literal">namespace.class</tt>.</p>
725 <div class="section" id="known-types">
726 <h3><a class="toc-backref" href="#id23">Known types</a></h3>
727 <dl class="docutils">
728 <dt><tt class="docutils literal">class</tt></dt>
729 <dd>A class.</dd>
730 <dt><tt class="docutils literal">enum</tt></dt>
731 <dd>An enumeration.</dd>
732 <dt><tt class="docutils literal">enumval</tt></dt>
733 <dd>An enumeration value.</dd>
734 <dt><tt class="docutils literal">field</tt></dt>
735 <dd>A field (of a class for example).</dd>
736 <dt><tt class="docutils literal">function</tt></dt>
737 <dd>A function.</dd>
738 <dt><tt class="docutils literal">interface</tt></dt>
739 <dd>An interface.</dd>
740 <dt><tt class="docutils literal">member</tt></dt>
741 <dd>A member (of a structure for example).</dd>
742 <dt><tt class="docutils literal">method</tt></dt>
743 <dd>A method.</dd>
744 <dt><tt class="docutils literal">namespace</tt></dt>
745 <dd>A namespace.</dd>
746 <dt><tt class="docutils literal">package</tt></dt>
747 <dd>A package.</dd>
748 <dt><tt class="docutils literal">prototype</tt></dt>
749 <dd>A prototype.</dd>
750 <dt><tt class="docutils literal">struct</tt></dt>
751 <dd>A structure.</dd>
752 <dt><tt class="docutils literal">typedef</tt></dt>
753 <dd>A type alias definition (<em>typedef</em> in C).</dd>
754 <dt><tt class="docutils literal">union</tt></dt>
755 <dd>An union.</dd>
756 <dt><tt class="docutils literal">variable</tt></dt>
757 <dd>A variable.</dd>
758 <dt><tt class="docutils literal">extern</tt></dt>
759 <dd><cite>???</cite></dd>
760 <dt><tt class="docutils literal">define</tt></dt>
761 <dd>A definition (like the <em>define</em> C preprocessor macro).</dd>
762 <dt><tt class="docutils literal">macro</tt></dt>
763 <dd>A macro.</dd>
764 <dt><tt class="docutils literal">file</tt></dt>
765 <dd>A file (will never match).</dd>
766 </dl>
767 </div>
768 </div>
769 <div class="section" id="rule-settings">
770 <h2><a class="toc-backref" href="#id24">Rule settings</a></h2>
771 <dl class="docutils">
772 <dt><tt class="docutils literal">template</tt> (string)</dt>
773 <dd><p class="first">A <a class="reference external" href="http://ctpl.tuxfamily.org/">CTPL</a> template that can include references to the following predefined
774 variables in addition to the file-type-wide and the global environments:</p>
775 <dl class="docutils">
776 <dt><tt class="docutils literal">argument_list</tt> (string list)</dt>
777 <dd>A list of the arguments of the currently documented symbol.</dd>
778 <dt><tt class="docutils literal">returns</tt> (boolean)</dt>
779 <dd>Indicates whether the currently documented symbol returns a value
780 (makes sense only for symbols that may return a value).</dd>
781 <dt><tt class="docutils literal">children</tt> (string list)</dt>
782 <dd>A list of the current symbol's first-level children. This is only set if
783 the rule's setting <tt class="docutils literal">children</tt> is set to <tt class="docutils literal">MERGE</tt>.</dd>
784 <dt><tt class="docutils literal">symbol</tt> (string)</dt>
785 <dd>The name of the symbol that is documented.</dd>
786 </dl>
787 <p><strong>[...]</strong></p>
788 <dl class="last docutils">
789 <dt><tt class="docutils literal">cursor</tt> (special, described below)</dt>
790 <dd>This can be used to mark in the template the position where the editor's
791 cursor should be moved to after comment insertion.
792 This mark will be removed from the generated documentation.
793 Note that even if this mark may occur as many times as you want in a
794 template, only the first will be actually honored, the latter being
795 only removed.</dd>
796 </dl>
797 </dd>
798 <dt><tt class="docutils literal">position</tt> (enumeration)</dt>
799 <dd><p class="first">The position where the documentation should be inserted. Possible values are:</p>
800 <dl class="last docutils">
801 <dt><tt class="docutils literal">BEFORE</tt> <a class="citation-reference" href="#default" id="id1">[default]</a></dt>
802 <dd>Inserts the documentation just before the symbol.</dd>
803 <dt><tt class="docutils literal">AFTER</tt></dt>
804 <dd>Inserts the documentation just after the symbol (currently quite limited, it
805 inserts the documentation at the end of the symbol's first line).</dd>
806 <dt><tt class="docutils literal">CURSOR</tt></dt>
807 <dd>Inserts the documentation at the current cursor position.</dd>
808 </dl>
809 </dd>
810 <dt><tt class="docutils literal">policy</tt> (enumeration)</dt>
811 <dd><p class="first">How the symbol is documented. Possible values are:</p>
812 <dl class="last docutils">
813 <dt><tt class="docutils literal">KEEP</tt> <a class="citation-reference" href="#default" id="id2">[default]</a></dt>
814 <dd>The symbol documents itself.</dd>
815 <dt><tt class="docutils literal">FORWARD</tt></dt>
816 <dd>Forward the documentation request to the parent. This is useful for symbols
817 that are documented by their parent, such as <a class="reference external" href="http://www.gtk.org/gtk-doc/">Gtk-Doc</a>'s enumerations.</dd>
818 <dt><tt class="docutils literal">PASS</tt></dt>
819 <dd>Completely ignore the symbol and handle the documentation request as if it
820 hasn't existed at all. This can be useful to ignore e.g. variables if they
821 are extracted by the tag parser of the language and you don't want to
822 document them, and don't want them to &quot;eat&quot; the documentation request.</dd>
823 </dl>
824 </dd>
825 <dt><tt class="docutils literal">children</tt> (enumeration)</dt>
826 <dd><p class="first">How the symbol's children can be used in the template. Possible values are:</p>
827 <dl class="last docutils">
828 <dt><tt class="docutils literal">SPLIT</tt> <a class="citation-reference" href="#default" id="id3">[default]</a></dt>
829 <dd>The symbol's children are provided as per-type lists.</dd>
830 <dt><tt class="docutils literal">MERGE</tt></dt>
831 <dd>The symbol's children are provided as a single list named <tt class="docutils literal">children</tt>.</dd>
832 </dl>
833 </dd>
834 <dt><tt class="docutils literal">matches</tt> (flags)</dt>
835 <dd>List of the children types that should be provided. Only useful if the
836 <tt class="docutils literal">children</tt> setting is set to <tt class="docutils literal">MERGE</tt>.
837 Defaults to all.
838 <strong>FIXME: check the exactitude of this description</strong></dd>
839 <dt><tt class="docutils literal">auto_doc_children</tt> (boolean)</dt>
840 <dd>Whether to also document symbol's children (according to their own rules).</dd>
841 </dl>
842 </div>
843 </div>
844 <div class="section" id="miscellaneous">
845 <h1><a class="toc-backref" href="#id25">Miscellaneous</a></h1>
846 <div class="section" id="configuration-directories">
847 <h2><a class="toc-backref" href="#id26">Configuration directories</a></h2>
848 <p>Configuration directories hold GeanyGenDoc's configuration. They are the
849 following:</p>
850 <ul class="simple">
851 <li>The user-specific configuration directory, containing the user-defined
852 settings is <tt class="docutils literal">$GEANY_USER_CONFIG/plugins/geanygendoc/</tt>.
853 <tt class="docutils literal">$GEANY_USER_CONFIG</tt> is generally <tt class="docutils literal"><span class="pre">~/.config/geany/</span></tt> on UNIX systems.</li>
854 <li>The system-wide configuration directory containing the default and
855 pre-installed configuration is <tt class="docutils literal">$GEANY_SYS_CONFIG/plugins/geanygendoc/</tt>.
856 <tt class="docutils literal">$GEANY_SYS_CONFIG</tt> is generally <tt class="docutils literal">/usr/share/geany/</tt> or
857 <tt class="docutils literal">/usr/local/share/geany</tt> on UNIX systems.</li>
858 </ul>
859 <p>When searching for a configuration, GeanyGenDoc will first look in the
860 user's configuration directory, and if it wasn't found there, in the system
861 configuration directory. If both failed, it assumes that there is no
862 configuration at all.</p>
863 </div>
864 </div>
865 <div class="section" id="appendix">
866 <h1><a class="toc-backref" href="#id27">Appendix</a></h1>
867 <div class="section" id="license">
868 <h2><a class="toc-backref" href="#id28">License</a></h2>
869 <div class="line-block">
870 <div class="line">GeanyGenDoc, a Geany plugin to ease generation of source code documentation</div>
871 <div class="line">Copyright (C) 2010-2011 Colomban Wendling &lt;ban(at)herbesfolles(dot)org&gt;</div>
872 </div>
873 <p>This program is free software: you can redistribute it and/or modify
874 it under the terms of the GNU General Public License as published by
875 the Free Software Foundation, either version 3 of the License, or
876 (at your option) any later version.</p>
877 <p>This program is distributed in the hope that it will be useful,
878 but WITHOUT ANY WARRANTY; without even the implied warranty of
879 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
880 GNU General Public License for more details.</p>
881 <p>You should have received a copy of the GNU General Public License
882 along with this program. If not, see &lt;<a class="reference external" href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>&gt;.</p>
883 </div>
884 <div class="section" id="configuration-syntax-summary">
885 <h2><a class="toc-backref" href="#id29">Configuration syntax summary</a></h2>
886 <pre class="literal-block">
887 string ::= ( &quot;&quot;&quot; .* &quot;&quot;&quot; | &quot;'&quot; .* &quot;'&quot; )
888 constant ::= [_A-Z][_A-Z0-9]+
889 integer ::= [0-9]+
890 boolean ::= ( &quot;True&quot; | &quot;False&quot; )
891 setting_value ::= ( string | constant | integer )
892 setting ::= &quot;setting-name&quot; &quot;=&quot; setting_value &quot;;&quot;
893 setting_list ::= ( &quot;{&quot; setting* &quot;}&quot; | setting )
894 setting_section ::= &quot;settings&quot; &quot;=&quot; setting_list
895
896 position ::= ( &quot;BEFORE&quot; | &quot;AFTER&quot; | &quot;CURSOR&quot; )
897 policy ::= ( &quot;KEEP&quot; | &quot;FORWARD&quot; | &quot;PASS&quot; )
898 children ::= ( &quot;SPLIT&quot; | &quot;MERGE&quot; )
899 type ::= ( &quot;class&quot; | &quot;enum&quot; | &quot;enumval&quot; | &quot;field&quot; |
900 &quot;function&quot; | &quot;interface&quot; | &quot;member&quot; | &quot;method&quot; |
901 &quot;namespace&quot; | &quot;package&quot; | &quot;prototype&quot; | &quot;struct&quot; |
902 &quot;typedef&quot; | &quot;union&quot; | &quot;variable&quot; | &quot;extern&quot; |
903 &quot;define&quot; | &quot;macro&quot; | &quot;file&quot; )
904 matches ::= type ( &quot;|&quot; type )*
905 doctype_subsetting ::= ( &quot;template&quot; &quot;=&quot; string |
906 &quot;position&quot; &quot;=&quot; position |
907 &quot;policy&quot; &quot;=&quot; policy |
908 &quot;children&quot; &quot;=&quot; children |
909 &quot;matches&quot; &quot;=&quot; matches |
910 &quot;auto_doc_children&quot; &quot;=&quot; boolean ) &quot;;&quot;
911 match ::= type ( &quot;.&quot; type )*
912 doctype_setting ::= ( match &quot;=&quot; &quot;{&quot; doctype_subsetting* &quot;}&quot; |
913 match &quot;.&quot; doctype_subsetting )
914 doctype_setting_list ::= ( &quot;{&quot; doctype_setting* &quot;}&quot; | doctype_setting )
915 doctype ::= &quot;doctype-name&quot; &quot;=&quot; doctype_setting_list
916 doctype_list ::= ( &quot;{&quot; doctype* &quot;}&quot; | doctype )
917 doctype_section ::= &quot;doctypes&quot; &quot;=&quot; doctype_list
918
919 document ::= ( setting_section? doctype_section? |
920 doctype_section? setting_section? )
921 </pre>
922 <!-- Content end, begin references -->
923 <!-- External links -->
924 <!-- -->
925 <!-- Internal links -->
926 <!-- -->
927 <hr class="docutils" />
928 <table class="docutils citation" frame="void" id="default" rules="none">
929 <colgroup><col class="label" /><col /></colgroup>
930 <tbody valign="top">
931 <tr><td class="label">[default]</td><td><em>(<a class="fn-backref" href="#id1">1</a>, <a class="fn-backref" href="#id2">2</a>, <a class="fn-backref" href="#id3">3</a>)</em> This is the default value of the setting</td></tr>
932 </tbody>
933 </table>
934 </div>
935 </div>
936 </div>
937 <div class="footer">
938 <hr class="footer" />
939 Generated on: 2015-06-22.
940
941 </div>
942 </body>
943 </html>