AuroraMiddleware/gtk2
1
0
Fork 0
forked from AuroraMiddleware/gtk
Code Issues Pull Requests Projects Releases Wiki Activity

Small updates to the coding and documentation style

Browse Source 
Mention summary sentences, and a few other things.
This commit is contained in:
Matthias Clasen 2021-03-05 12:44:41 -05:00 committed by Emmanuele Bassi
parent 686f65f267
commit d13e592dbf
2 changed files with 44 additions and 32 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

45
docs/CODING-STYLE.md
View File

@ -696,27 +696,29 @@ Public macros should not be used unless they evaluate to a constant.
### Symbol visibility ### Symbol visibility
Any symbol that is not explicitly annotated using a `GDK_AVAILABLE_IN_*` Any symbol that is not explicitly annotated using a `GDK_AVAILABLE_IN_*`
macro is considered internal, and not exported in the shared library. or `GDK_DEPRECATED_IN_*` macro is considered internal, and not exported
in the shared library.
Never export variables as public API, since this is cumbersome on some Never export variables as public API, since this is cumbersome on some
platforms. It is always preferable to add getters and setters instead. platforms. It is always preferable to add getters and setters instead.
Non-exported functions that are needed in more than one source file Non-exported functions that are needed in more than one source file
should be declared in a private header file. should be declared in a private header file with a name that ends in
`private.h`.
Non-exported functions that are only needed in one source file Non-exported functions that are only needed in one source file
should be declared static. should be declared static.
### Documentation ### Documentation
All public APIs must have gtk-doc comments. For functions, these should All public APIs must have doc comments. For functions, these should
be placed in the source file, directly above the function. be placed in the source file, directly above the function.
```c ```c
/* valid */ /* valid */
/** /**
* gtk_get_flow: * gtk_get_flow:
* @widget: a #GtkWidget * @widget: a `GtkWidget`
* *
* Gets the flow of a widget. * Gets the flow of a widget.
* *
@ -736,29 +738,34 @@ be placed in the source file, directly above the function.
Doc comments for macros, function types, class structs, etc should be Doc comments for macros, function types, class structs, etc should be
placed next to the definitions, typically in headers. placed next to the definitions, typically in headers.
Section introductions should be placed in the source file they describe, The main content of the doc comments uses markdown, which can include
after the license header: inline formatting, sections, tables, images, links. For links to
symbols/classes/etc, we use a markdown extension syntax like this:
[class@Gtk.Widget], [method@Gtk.ListView.get_factory],...
Every doc comment should start with a single-sentence paragraph that
can serve as a summary of sorts (it will often be placed next to a
link pointing to the full documentation for the symbol/class/etc).
The summary should not include links.
Long-form documentation for classes should be included in the doc
comment for the struct, typically at the top of the source file,
after the license header and includes:
```c ```c
/* valid */
/** /**
* SECTION:gtksizerequest * GtkSizeRequest:
* @Short_Description: Height-for-width geometry management *
* @Title: GtkSizeRequest * The GtkSizeRequest interface is GTK's height-for-width geometry
* geometry management system.
*
* # Geometry management
* *
* The GtkSizeRequest interface is GTK's height-for-width (and
* width-for-height) geometry management system.
* ... * ...
*/ */
``` ```
To properly document a new function, macro, function type or struct,
it needs to be listed in the `sections.txt` file.
To properly document a new class, it needs to be given its own section
in the sections.txt, needs to be included in the `docs.xml` file, and the
`get_type` function needs to listed in the `.types` file.
For more information on the documentation style and contribution guidelines, For more information on the documentation style and contribution guidelines,
please [follow the corresponding contribution guide](./reference/README.md). please [follow the corresponding contribution guide](./reference/README.md).

31
docs/reference/README.md
View File

@ -6,22 +6,21 @@ The GTK documentation is divided in two major components:
source code source code
- static pages that provide an overview of specific sections of the API - static pages that provide an overview of specific sections of the API
In both cases, the contents are parsed, converted into DocBook format, and In both cases, the contents are parsed as markdown and cross-linked in order
cross-linked in order to match types, functions, signals, and properties. to match types, functions, signals, and properties. Ultimatively, we generate
From the DocBook output, we generate HTML, which can be used to read the HTML, which can be used to read the documentation both offline and online.
documentation both offline and online.
In both cases, contributing to the GTK documentation requires modifying Contributing to the GTK documentation requires modifying files tracked in the
files tracked in the source control repository, and follows the same steps source control repository, and follows the same steps as any other code
as any other code contribution as outlined in the GTK [contribution contribution as outlined in the GTK [contribution guide][contributing].
guide][contributing]. Please, refer to that document for any further Please, refer to that document for any further question on the mechanics
question on the mechanics of contributing to GTK. of contributing to GTK.
GTK uses [gtk-doc][gtkdoc] to generate its documentation. Please, visit the GTK uses [gi-docgen][gidocgen] to generate its documentation. Please, visit
gtk-doc website to read the project's documentation. the gi-docgen website to read the project's documentation.
[contributing]: ../../CONTRIBUTING.md [contributing]: ../../CONTRIBUTING.md
[gtkdoc]: https://wiki.gnome.org/DocumentationProject/GtkDoc [gi-docgen]: https://gitlab.gnome.org/ebassi/gi-docgen
## Contributing to the API reference ## Contributing to the API reference
@ -41,7 +40,7 @@ above the type or function declaration. For instance:
*/ */
gboolean gboolean
gtk_foo_set_bar (GtkFoo *self, gtk_foo_set_bar (GtkFoo *self,
GtkBar *bar) GtkBar *bar)
{ {
... ...
``` ```
@ -97,6 +96,11 @@ the GTK documentation supports additional link formats, like:
For more information on the available link formats, see the gi-docgen For more information on the available link formats, see the gi-docgen
documentation. documentation.
Every doc comment should start with a single-sentence paragraph that
can serve as a summary of sorts (it will often be placed next to a
link pointing to the full documentation for the symbol/class/etc).
The summary should not include links.
### Introspection annotations ### Introspection annotations
The purpose of the annotations for function arguments, properties, signals, The purpose of the annotations for function arguments, properties, signals,
@ -121,6 +125,7 @@ For widget classes, the description should also contain:
custom GtkBuildable implementation custom GtkBuildable implementation
- the CSS element name to be used by selectors - the CSS element name to be used by selectors
- the CSS selector hierarchy for children, in case of a composite widget - the CSS selector hierarchy for children, in case of a composite widget
- the accessible role of the class
Each section in a type description can have a heading; it's preferred to use Each section in a type description can have a heading; it's preferred to use
second and third level headings only. second and third level headings only.