| 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 "c" 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 |
"doxygen" and "gtkdoc".</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 = "A string. # This isn't a comment but a string"; |
| 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">"</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">\"</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 |
"This is a string with \"special\" characters.\nThis is another line!" |
| 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 "c" or "python".</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 = " /**< {cursor} */"; |
| 695 |
position = AFTER; |
| 696 |
} |
| 697 |
struct.template = "/**\n * @brief: {cursor}\n * \n * \n */\n"; |
| 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">-></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">-></span> class <span class="pre">-></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">-></span> class</tt> but not one with |
| 721 |
<tt class="docutils literal">class <span class="pre">-></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">-></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 "eat" 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 <ban(at)herbesfolles(dot)org></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 <<a class="reference external" href="http://www.gnu.org/licenses/">http://www.gnu.org/licenses/</a>>.</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 ::= ( """ .* """ | "'" .* "'" ) |
| 888 |
constant ::= [_A-Z][_A-Z0-9]+ |
| 889 |
integer ::= [0-9]+ |
| 890 |
boolean ::= ( "True" | "False" ) |
| 891 |
setting_value ::= ( string | constant | integer ) |
| 892 |
setting ::= "setting-name" "=" setting_value ";" |
| 893 |
setting_list ::= ( "{" setting* "}" | setting ) |
| 894 |
setting_section ::= "settings" "=" setting_list |
| 895 |
|
| 896 |
position ::= ( "BEFORE" | "AFTER" | "CURSOR" ) |
| 897 |
policy ::= ( "KEEP" | "FORWARD" | "PASS" ) |
| 898 |
children ::= ( "SPLIT" | "MERGE" ) |
| 899 |
type ::= ( "class" | "enum" | "enumval" | "field" | |
| 900 |
"function" | "interface" | "member" | "method" | |
| 901 |
"namespace" | "package" | "prototype" | "struct" | |
| 902 |
"typedef" | "union" | "variable" | "extern" | |
| 903 |
"define" | "macro" | "file" ) |
| 904 |
matches ::= type ( "|" type )* |
| 905 |
doctype_subsetting ::= ( "template" "=" string | |
| 906 |
"position" "=" position | |
| 907 |
"policy" "=" policy | |
| 908 |
"children" "=" children | |
| 909 |
"matches" "=" matches | |
| 910 |
"auto_doc_children" "=" boolean ) ";" |
| 911 |
match ::= type ( "." type )* |
| 912 |
doctype_setting ::= ( match "=" "{" doctype_subsetting* "}" | |
| 913 |
match "." doctype_subsetting ) |
| 914 |
doctype_setting_list ::= ( "{" doctype_setting* "}" | doctype_setting ) |
| 915 |
doctype ::= "doctype-name" "=" doctype_setting_list |
| 916 |
doctype_list ::= ( "{" doctype* "}" | doctype ) |
| 917 |
doctype_section ::= "doctypes" "=" 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> |