docs: Update the documentation style guide

docs/reference/README.md

@@ -26,18 +26,20 @@ gtk-doc website to read the project's documentation.
 ## 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
+function, you will need to edit a comment stanza, typically right
 above the type or function declaration. For instance:
 
 ```c
 /**
  * gtk_foo_set_bar:
- * @self: a #GtkFoo
- * @bar: a #GtkBar
+ * @self: a foo widget
+ * @bar: (nullable): the bar to set
  *
- * Sets the given #GtkBar instance on a #GtkFoo widget.
+ * Sets the given `GtkBar` instance on a foo widget.
+ *
+ * Returns: `TRUE` if the bar was set
  */
-void
+gboolean
 gtk_foo_set_bar (GtkFoo *self,
 		 GtkBar *bar)
 {
@@ -51,31 +53,14 @@ Or, for types:
  * GtkFoo:
  *
  * A foo widget instance.
- *
- * The contents of this structure are private and should never
- * be accessed directly.
  */
 struct _GtkFoo
 {
+  /*< private >*/
   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.
 
@@ -90,49 +75,55 @@ unrelated reasons.
 
 ### 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
+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 identical to the one 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:
+the GTK documentation supports additional link formats, like:
 
-`#ClassName`
+`[class@Namespace.ClassName]`
  : Creates a link to the docs for a class
 
-`function()`
- : Creates a link to the docs for a function
+`[method@Namespace.Method.name]`
+ : Creates a link to the docs for a method in a class
 
-`%constant`
- : Generates suitable markup for enum values or constants
+`[func@Namespace.function]`
+ : Creates a link to the docs for a global function
 
-### Sections
+For more information on the available link formats, see the gi-docgen
+documentation.
 
- - 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:
+### Introspection annotations
 
-```c
-/**
- * SECTION:gtkshortcut
- * @Title: GtkShortcut
- * @Short_desc: A key shortcut
- *
- * ...
-```
+The purpose of the annotations for function arguments, properties, signals,
+etc., is to describe the API in a machine readable way. The annotations
+are consumed by language bindings and by the documentation tools.
 
-   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
+For more information about the annotations used by GTK, you should refer to
+the [GObject Introspection documentation][gi-annotations].
+
+[gi-annotations]: https://gi.readthedocs.io/en/latest/annotations/giannotations.html
+
+### Type description
+
+Each type should be annotated with a description of what the type does.
+
+For classes, the description should contain an overview of the type;
+what it does; typical use cases; and idiomatic examples of its use.
+
+For widget classes, the description 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
+
+Each section in a type description can have a heading; it's preferred to use
+second and third level headings only.
 
 ### Functions
 
@@ -155,17 +146,26 @@ Checks whether the widget is set to be visible or not.
  - 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 is a setter or a getter for an object property, you should
+   add an `(attributes org.gtk.Method.set_property=property-name)` or a
+   an `(attributes org.gtk.Method.get_property=property-name)` annotation
+   to the method's identifier
  - 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.
+ - If a method is a signal emitter, you should use the
+   `(attributes org.gtk.Method.signal=signal-name)` annotation in
+   the method's identifier
+
+### Arguments and return values
+
+ - Arguments should be descriptive, but short
+ - There is no need to mention the type of the argument
+ - Always annotate nullability, direction, and ownership transfer
 
 ### Signals
 
  - While GObject can introspect argument and return types for signals,
-   you should *always* document them with an explicit gtk-doc stanza.
+   you should *always* document them with an explicit documentation stanza.
  - The syntax for signal stanzas is similar to functions:
 
 ```c
@@ -181,12 +181,15 @@ Checks whether the widget is set to be visible or not.
 
  - 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
+   *always* document them with an explicit documentation 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.
+ - If the property has public accessors you should annotate it with
+   the `(attributes org.gtk.Property.set=setter_function)` and
+   `(attributes org.gtk.Property.get=getter_function)` attributes
  - The syntax for property documentation is:
 
 ```c
@@ -198,8 +201,9 @@ Checks whether the widget is set to be visible or not.
 
 ### Actions
 
- - Actions are new in GTK 4, and gtk-doc had to learn a new syntax
-   to document them:
+ - Actions are new in GTK 4, and describe an action associated to
+   a widget class
+ - The syntax for action documentation is:
 
 ```
 /**c