From d13e592dbfb15888f4a905d80a221ee7d62848b4 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Fri, 5 Mar 2021 12:44:41 -0500 Subject: [PATCH] Small updates to the coding and documentation style Mention summary sentences, and a few other things. --- docs/CODING-STYLE.md | 45 +++++++++++++++++++++++----------------- docs/reference/README.md | 31 +++++++++++++++------------ 2 files changed, 44 insertions(+), 32 deletions(-) diff --git a/docs/CODING-STYLE.md b/docs/CODING-STYLE.md index 11d105edd9..d48df10f6f 100644 --- a/docs/CODING-STYLE.md +++ b/docs/CODING-STYLE.md @@ -696,27 +696,29 @@ Public macros should not be used unless they evaluate to a constant. ### Symbol visibility 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 platforms. It is always preferable to add getters and setters instead. 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 should be declared static. ### 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. ```c /* valid */ /** * gtk_get_flow: - * @widget: a #GtkWidget + * @widget: a `GtkWidget` * * 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 placed next to the definitions, typically in headers. -Section introductions should be placed in the source file they describe, -after the license header: +The main content of the doc comments uses markdown, which can include +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 - /* valid */ /** - * SECTION:gtksizerequest - * @Short_Description: Height-for-width geometry management - * @Title: GtkSizeRequest + * 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, please [follow the corresponding contribution guide](./reference/README.md). diff --git a/docs/reference/README.md b/docs/reference/README.md index f0f33e1af2..6594f58f36 100644 --- a/docs/reference/README.md +++ b/docs/reference/README.md @@ -6,22 +6,21 @@ The GTK documentation is divided in two major components: 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, the contents are parsed as markdown and cross-linked in order +to match types, functions, signals, and properties. Ultimatively, 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. +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. +GTK uses [gi-docgen][gidocgen] to generate its documentation. Please, visit +the gi-docgen website to read the project's documentation. [contributing]: ../../CONTRIBUTING.md -[gtkdoc]: https://wiki.gnome.org/DocumentationProject/GtkDoc +[gi-docgen]: https://gitlab.gnome.org/ebassi/gi-docgen ## Contributing to the API reference @@ -41,7 +40,7 @@ above the type or function declaration. For instance: */ gboolean 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 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 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 - the CSS element name to be used by selectors - 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 second and third level headings only.