[gtk/ebassi/gidocgen: 497/500] Small updates to the coding and documentation style

[Emmanuele Bassi <ebassi src gnome org>]

commit d13e592dbfb15888f4a905d80a221ee7d62848b4
Author: Matthias Clasen <mclasen redhat com>
Date:   Fri Mar 5 12:44:41 2021 -0500

    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.