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
212
213
214
215
216
217
218
219
|
.. SPDX-FileCopyrightText: 2021 GNOME Foundation
..
.. SPDX-License-Identifier: Apache-2.0 OR GPL-3.0-or-later
=====================
Linking items by name
=====================
Gi-docgen is capable of linking symbols across the same introspected namespace,
by using a qualifier fragment and the symbol name.
For instance:
.. code-block:: c
/**
* ExampleFoo:
*
* This structure is related to [struct@Bar].
*/
/**
* example_foo_set_bar:
*
* Sets [struct@Example.Bar] on an instance of `Foo`.
*/
/**
* ExampleFoo::bar-changed:
*
* Emitted when the [bar instance][struct@Example.Bar] changes.
/
/**
* ExampleFoo:bar:
*
* Sets an instance of [`Bar`](struct.Bar.html) on `Foo`.
*/
will all link to ``Bar``.
Backticks will be stripped, so ``[`class@Foo`]`` will correctly link to ``Foo``.
Fragment identifiers can be included to link to anchors in the target page:
``[class@Foo#some-subheading]``. All subheadings in gi-docgen generated pages
have an automatically generated anchor.
The link can either be a fully qualified name, which includes the namespace; or
a name relative to the current namespace; for instance, both of the following links
will point to ``ExampleFoo`` when generating the documentation for the "Example"
namespace:
- ``[class@Foo]``
- ``[class@Example.Foo]``
The available qualifier fragments are:
.. list-table::
:widths: 10 15 25 50
:header-rows: 1
* - Fragment
- Argument
- Description
- Example
* - ``alias``
- ``TypeName``
- An alias to another type
- ``[alias@Allocation]``
* - ``callback``
- ``TypeName``
- A callback type
- ``[callback@Gtk.ListBoxForeachFunc]``
* - ``class``
- ``TypeName``
- An object class
- ``[class@Widget]``, ``[class@Gdk.Surface]``, ``[class@Gsk.RenderNode]``
* - ``const``
- ``CONSTANT``
- A constant or pre-processor symbol
- ``[const@Gdk.KEY_q]``
* - ``ctor``
- ``TypeName.constructor``
- A constructor function
- ``[ctor@Gtk.Box.new]``, ``[ctor@Button.new_with_label]``
* - ``enum``
- ``TypeName``
- A plain enumeration or member
- ``[enum@Orientation]``, ``[enum@Orientation.HORIZONTAL]``
* - ``error``
- ``TypeName``
- A ``GError`` domain enumeration or member
- ``[error@Gtk.BuilderParseError]``, ``[error@Gtk.FileChooserError.NONEXISTENT]``
* - ``flags``
- ``TypeName``
- A bitfield or member
- ``[flags@Gdk.ModifierType]``, ``[flags@Gdk.ModifierType.SHIFT_MASK]``
* - ``func``
- ``function``, ``TypeName.function``
- A global or a type function
- ``[func@Gtk.init]``, ``[func@show_uri]``, ``[func@Gtk.Window.list_toplevels]``
* - ``iface``
- ``TypeName``
- A ``GTypeInterface``
- ``[iface@Gtk.Buildable]``
* - ``method``
- ``TypeName.method``, ``TypeNameClass.method``
- An instance or class method
- ``[method@Gtk.Widget.show]``, ``[method@WidgetClass.add_binding]``
* - ``property``
- ``TypeName:property``
- A ``GObject`` property
- ``[property@Gtk.Orientable:orientation]``
* - ``signal``
- ``TypeName::signal``
- A ``GObject`` signal
- ``[signal@Gtk.RecentManager::changed]``
* - ``struct``
- ``TypeName``
- A plain C structure or union
- ``[struct@Gtk.TextIter]``
* - ``vfunc``
- ``TypeName.virtual``
- A virtual function in a class or interface
- ``[vfunc@Gtk.Widget.measure]``
* - ``type``
- ``TypeName``
- A registered type
- ``[type@Widget]``, ``[type@Gdk.ModifierType]``, ``[type@Gtk.TextIter]``
* - ``id``
- ``function``
- A C symbol
- ``[id@gtk_window_new]``, ``[id@g_signal_connect]``
The generic ``type`` fragment, followed by a type, will look up the given type
and generate the appropriate link for it. The type can be fully qualified or
relative to the current namespace:
::
// Equivalent to [class@Gtk.Window]
[type@Gtk.Window]
// Equivalent to [enum@Gtk.Orientation]
[type@Gtk.Orientation]
Anything that is a known type—aliases, callbacks, classes, constants,
enumerations, interfaces, structures—can be linked using the ``type`` fragment.
Additionally, the ``id`` fragment, followed by a C symbol identifier, will try
to link to the function; for instance:
::
// Equivalent to [func@Gtk.show_uri], will link to gtk_show_uri()
[id@gtk_show_uri]
// Equivalent to [method@Gtk.Widget.show], will link to gtk_widget_show()
[id@gtk_widget_show]
// Equivalent to [func@GObject.signal_emit], will link to g_signal_emit()
[id@g_signal_emit]
It's important to note that the ``method`` and ``func`` fragments can have
multiple meanings:
- the ``method`` fragment will match both instance and class methods, depending
on the type used; for instance, to match an instance method you should use the
type name, and to match a class method you should use the class name. The class
method should not be confused with the ``vfunc`` fragment, which uses the type
name and links to virtual methods defined in the class or interface structure.
Class methods take the class pointer as their first argument, whereas virtual
methods take the instance pointer as their first argument.
::
// will link to gtk_widget_show()
[method@Gtk.Widget.show]
// will link to gtk_widget_class_add_binding()
[method@Gtk.WidgetClass.add_binding]
// will link to GtkWidgetClass.show
[vfunc@Gtk.Widget.show]
- similarly, the ``func`` fragment will match global functions and type
functions, depending on whether the link contains a type or not. Additionally,
``func`` will match function macros, which are part of the global namespace.
::
// will link to gtk_show_uri()
[func@Gtk.show_uri]
// will link to gtk_window_list_toplevels()
[func@Gtk.Window.list_toplevels]
// will link to gtk_widget_class_bind_template_child()
[func@Gtk.widget_class_bind_template_child]
External Links
--------------
Gi-docgen can use the same syntax to point to symbols in other namespaces
with gi-docgen-generated documentation, as long as you provide it with
a mapping from the namespace names to a base url for the docs. This is
done by defining a JavaScript map called ``baseURLs`` like this:
.. code-block:: js
baseURLs = [
[ 'Pango', 'https://gnome.pages.gitlab.gnome.org/pango/Pango/' ],
[ 'PangoCairo', 'https://gnome.pages.gitlab.gnome.org/pango/PangoCairo/' ],
]
And specifying the path of the JavaScript file into the ``extra`` section
of the project configuration, in the ``urlmap_file`` key.
|
