First of all, welcome to this manual. Then, what is GeanyGenDoc? It is a plug-in for Geany as you might have noticed; but what is it meant to do? Basically, it generates and inserts text chunks, particularly from document's symbols. Its goal is to ease writing documentation for the good.
If you are impatient, you will probably want to discover the user interface in Geany first; but if you have the time to discover the tool, take a look at the design and learn how GeanyGenDoc works and how you can make the most of it.
The preferences dialog, that can either be opened through Edit → Plugin Preferences or with the Preferences button in the plugin manager, allows to modify the following preferences:
GeanyGenDoc has an extensible design based on three points: file type, documentation type and rules.
The syntax used by the configuration files is an extended key-value tree definition based on common concepts (trees, string literals, semicolon-ended values, etc.).
The key-value syntax is as follows:
key = value
where value is either a semicolon-ended single value:
value;
or a brace-surrounded list of key-value pairs that use the same syntax again:
{
key1 = value1
key2 = value2
}
Here a little example of the syntax (not any actual configuration example):
key1 = value1;
key2 = {
sub-key1 = sub-value1;
sub-key2 = {
sub-sub-key1 = sub-sub-value1;
}
}
Key-value pairs are often referred as group when they are meant to have multiple values and as setting when they have a single value.
Is considered as comment (and therefore ignored) everything between a number sign (#) and the following end of line, unless the # occurs as part of another syntactic element (such as a string literal).
A short example:
# This is a comment key = value; # This is also a comment string = "A string. # This isn't a comment but a string";
A string literal. String literals are surrounded by either single (') or double (") quotes.
Some special characters can be inserted in a string with an escape sequence:
Note that backslashes are used as the escaping character, which means that it must be escaped to be treated as a simple backslash character.
A simple example:
"This is a string with \"special\" characters.\nThis is another line!"
A logical OR of named constants. This is similar to enumerations but can combine different values.
The syntax is common for such types and uses the pipe (|) as combination character. Considering the A, B and C constants, a valid value could be A | C, which represents both A and C but not B.
The file type determines which configuration applies to which document. File type identifiers are the lowercased name of Geany's file type, for example "c" or "python".
Configuration for a particular file type goes in a file named file-type-identifier.conf in the filetypes sub-directory of a configuration directory.
A file type configuration can contain two type of things: file-type-wide settings and any number of documentation types.
This group contains the file-type-wide settings.
This group contains a list of documentation types.
A documentation type is a named set of rules for a file type, describing how to generate a particular type of documentation (i.e. Doxygen, Gtk-Doc, Valadoc or whatever).
A documentation type is identified by its name and must therefore be unique in a file type. But of course, different file types can define the same documentation type. It is even recommended for a better consistency to use the same identifier in different file types when they generate the same type of documentation (even though it is completely up to you).
doxygen = {
struct.member = {
template = " /**< {cursor} */";
position = AFTER;
}
struct.template = "/**\n * @brief: {cursor}\n * \n * \n */\n";
}
Rules are the actual definition of how documentation is generated. A rule applies to a symbol type and hierarchy, allowing fine control over which and how symbols are documented.
A rule is represented as a group of settings in a documentation type. The name of this group is the type hierarchy to which the settings applies.
A type hierarchy is a hierarchy of the types that a symbol must have to match this rule.
In the symbol side, the type hierarchy is the types of the symbol's parents, terminated by the symbol's own type. For example, a method in a class would have a hierarchy like class -> method; and if the class is itself in a namespace, the hierarchy would the look like namespace -> class -> method, and so on.
For a rule to apply, its type hierarchy must match the end of the symbol type hierarchy. For example a rule with the type hierarchy class will match a symbol with the type hierarchy namespace -> class but not one with class -> method.
A type hierarchy uses dots (.) to separate types and build the hierarchy. For example, the type hierarchy representing namespace -> class would be written namespace.class.
A CTPL template that can include references to the following predefined variables in addition to the file-type-wide and the global environments:
[...]
The position where the documentation should be inserted. Possible values are:
How the symbol is documented. Possible values are:
How the symbol's children can be used in the template. Possible values are:
Configuration directories hold GeanyGenDoc's configuration. They are the following:
When searching for a configuration, GeanyGenDoc will first look in the user's configuration directory, and if it wasn't found there, in the system configuration directory. If both failed, it assumes that there is no configuration at all.
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 3 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, see <http://www.gnu.org/licenses/>.
string ::= ( """ .* """ | "'" .* "'" )
constant ::= [_A-Z][_A-Z0-9]+
integer ::= [0-9]+
boolean ::= ( "True" | "False" )
setting_value ::= ( string | constant | integer )
setting ::= "setting-name" "=" setting_value ";"
setting_list ::= ( "{" setting* "}" | setting )
setting_section ::= "settings" "=" setting_list
position ::= ( "BEFORE" | "AFTER" | "CURSOR" )
policy ::= ( "KEEP" | "FORWARD" | "PASS" )
children ::= ( "SPLIT" | "MERGE" )
type ::= ( "class" | "enum" | "enumval" | "field" |
"function" | "interface" | "member" | "method" |
"namespace" | "package" | "prototype" | "struct" |
"typedef" | "union" | "variable" | "extern" |
"define" | "macro" | "file" )
matches ::= type ( "|" type )*
doctype_subsetting ::= ( "template" "=" string |
"position" "=" position |
"policy" "=" policy |
"children" "=" children |
"matches" "=" matches |
"auto_doc_children" "=" boolean ) ";"
match ::= type ( "." type )*
doctype_setting ::= ( match "=" "{" doctype_subsetting* "}" |
match "." doctype_subsetting )
doctype_setting_list ::= ( "{" doctype_setting* "}" | doctype_setting )
doctype ::= "doctype-name" "=" doctype_setting_list
doctype_list ::= ( "{" doctype* "}" | doctype )
doctype_section ::= "doctypes" "=" doctype_list
document ::= ( setting_section? doctype_section? |
doctype_section? setting_section? )
| [default] | (1, 2, 3) This is the default value of the setting |