1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
|
# How to contribute to GTK's documentation
The GTK documentation is divided in two major components:
- the API reference, which is generated from special comments in the GTK
source code
- static pages that provide an overview of specific sections of the API
In both cases, the contents are parsed, converted into DocBook format, and
cross-linked in order to match types, functions, signals, and properties.
From the DocBook output, we generate HTML, which can be used to read the
documentation both offline and online.
In both cases, contributing to the GTK documentation requires modifying
files tracked in the source control repository, and follows the same steps
as any other code contribution as outlined in the GTK [contribution
guide][contributing]. Please, refer to that document for any further
question on the mechanics of contributing to GTK.
GTK uses [gtk-doc][gtkdoc] to generate its documentation. Please, visit the
gtk-doc website to read the project's documentation.
[contributing]: ../../CONTRIBUTING.md
[gtkdoc]: https://wiki.gnome.org/DocumentationProject/GtkDoc
## Contributing to the API reference
Whenever you need to add or modify the documentation of a type or a
function, you will need to edit a `gtk-doc` comment stanza, typically right
above the type or function declaration. For instance:
```c
/**
* gtk_foo_set_bar:
* @self: a #GtkFoo
* @bar: a #GtkBar
*
* Sets the given #GtkBar instance on a #GtkFoo widget.
*/
void
gtk_foo_set_bar (GtkFoo *self,
GtkBar *bar)
{
...
```
Or, for types:
```c
/**
* GtkFoo:
*
* A foo widget instance.
*
* The contents of this structure are private and should never
* be accessed directly.
*/
struct _GtkFoo
{
GtkWidget parent_instance;
};
```
Each public function and type in the GTK API reference must be listed in the
`sections.txt` file for the specific namespace to which it belongs: GDK,
GSK, or GTK. For instance, if you add a function named `gtk_foo_set_bar()`,
you will need to:
1. open `docs/reference/gtk/gtk4-sections.txt`
1. find the section that lists the symbols of the `GtkFoo` type
1. add `gtk_foo_set_bar` to the list
New classes require:
1. a new section in the `sections.txt` file
1. the `get_type` function added to the `.types` file
1. an `xinclude` element in the `docs.xml` file
The GTK documentation also contains a number of 'freestanding' chapters
for which the source is in .md files in docs/reference/gtk.
## Style guide
Like the [coding style][coding], these rules try to formalize the existing
documentation style; in general, you should only ever modify existing code
that does not match the rules if you're already changing that code for
unrelated reasons.
[coding]: ../CODING-STYLE.md
### Syntax
The input syntax for GTK documentation is markdown, in a flavor that is
similar to what you see on gitlab or github. The markdown support for
fragments that are extracted from sources is more limited than for
freestanding chapters. As an exception, man pages for tools are currently
maintained in docbook, since the conversion from markdown to docbook is
losing too much of the expected formatting.
In addition to typical markdown formatting such as \*emphasis\* or \_italics\_,
gtk-doc supports a few abbreviations for cross-references and formatting:
`#ClassName`
: Creates a link to the docs for a class
`function()`
: Creates a link to the docs for a function
`%constant`
: Generates suitable markup for enum values or constants
### Sections
- The "section" of each type must contain a name, to be referenced in the
`sections.txt` file; a title; and a short description. For instance:
```c
/**
* SECTION:gtkshortcut
* @Title: GtkShortcut
* @Short_desc: A key shortcut
*
* ...
```
For classes, the title should be the name of the class. While it's
possible to add section titles directly to the `sections.txt` file, this
is considered deprecated, and should not be done for newly written code.
- For classes, the long description should contain an overview of the type;
what it does; typical use cases; and idiomatic examples of its use.
- For widget classes, the long description of a section should also contain:
- special XML elements and attributes parsed by the class, in case of a
custom GtkBuildable implementation
- the CSS element name to be used by selectors
- the CSS selector hierarchy for children, in case of a composite widget
### Functions
- The argument names must match in the declaration, definition, and
documentation stanza.
- The description should refer to the function as the subject, e.g.:
```
Adds a shortcut to the shortcuts controller.
```
Or:
```
Checks whether the widget is set to be visible or not.
```
### Methods
- Methods are special functions whose first argument is always the instance
of a certain class. The instance argument for newly written code should be
called `self`.
- If a method is a setter or a getter for an object property, link the
property in the methods's description.
- If a method changes one or more properties as side effect, link those
properties in the method's description
- If a method is a signal emitter, link the signal in the method's
description.
### Signals
- While GObject can introspect argument and return types for signals,
you should *always* document them with an explicit gtk-doc stanza.
- The syntax for signal stanzas is similar to functions:
```c
/**
* GtkFoo::signal-name:
* @arg1: ...
* @arg2: ...
*
* ...
```
### Properties
- While GObject properties contain text that can be extracted
programmatically in order to build their documentation, you should
*always* document them with an explicit gtk-doc stanza. The text
associated to the property is short and meant to be used when
programmatically building user interfaces, and not for documentation
purposes.
- Always note if setting a property has side effects, like causing another
property to change state.
- The syntax for property documentation is:
```c
/**
* GtkFoo:property-name:
*
* ...
```
### Actions
- Actions are new in GTK 4, and gtk-doc had to learn a new syntax
to document them:
```
/**c
* GtkFoo|action-name:
* @arg1: ...
* @arg2: ...
*
* ...
```
|
