[gtk-doc] mkdb: add glossary entries for stability levels

[Stefan Kost <stefkost src gnome org>]

commit 90713c99566e1bc51597a44cceb270c4ba84c8cf
Author: Stefan Sauer <ensonic users sf net>
Date:   Mon Feb 17 21:56:52 2014 +0100

    mkdb: add glossary entries for stability levels
    
    Add the definitions for stabiloity levels to the glossary.
    
    Fixes #170860

 gtkdoc-mkdb.in                             |   48 +++++++++++++++++++++++----
 style/style.css                            |    5 +++
 tests/annotations/docs/tester-sections.txt |    1 +
 tests/annotations/src/tester.c             |   14 ++++++++
 tests/annotations/src/tester.h             |   22 +++++++------
 5 files changed, 73 insertions(+), 17 deletions(-)
---
diff --git a/gtkdoc-mkdb.in b/gtkdoc-mkdb.in
index a26e792..9392892 100755
--- a/gtkdoc-mkdb.in
+++ b/gtkdoc-mkdb.in
@@ -300,9 +300,9 @@ $PreProcessorDirectives{"warning"} = 1;
 # remember used annotation (to write minimal glossary)
 my %AnnotationsUsed;
 
-# the annotations are defined at:
-# https://live.gnome.org/GObjectIntrospection/Annotations
 my %AnnotationDefinition = (
+    # the GObjectIntrospection annotations are defined at:
+    # https://live.gnome.org/GObjectIntrospection/Annotations
     'allow-none' => "NULL is ok, both for passing and for returning.",
     'array' => "Parameter points to an array of items.",
     'attribute' => "Deprecated free-form custom annotation, replaced by (attributes) annotation.",
@@ -337,7 +337,37 @@ my %AnnotationDefinition = (
     'type' => "Override the parsed C type with given type.",
     'unref-func' => "The specified function is used to unref a struct, must be a GTypeInstance.",
     'virtual' => "This is the invoker for a virtual method.",
-    'value' => "The specified value overrides the evaluated value of the constant."
+    'value' => "The specified value overrides the evaluated value of the constant.",
+    # Stability Level definition
+    # https://bugzilla.gnome.org/show_bug.cgi?id=170860
+    'Stable' => <<EOF,
+The intention of a Stable interface is to enable arbitrary third parties to
+develop applications to these interfaces, release them, and have confidence that
+they will run on all minor releases of the product (after the one in which the
+interface was introduced, and within the same major release). Even at a major
+release, incompatible changes are expected to be rare, and to have strong
+justifications.
+EOF
+    'Unstable' => <<EOF,
+Unstable interfaces are experimental or transitional. They are typically used to
+give outside developers early access to new or rapidly changing technology, or
+to provide an interim solution to a problem where a more general solution is
+anticipated. No claims are made about either source or binary compatibility from
+one minor release to the next.
+
+The Unstable interface level is a warning that these interfaces are  subject to
+change without warning and should not be used in unbundled products.
+
+Given such caveats, customer impact need not be a factor when considering
+incompatible changes to an Unstable interface in a major or minor release.
+Nonetheless, when such changes are introduced, the changes should still be
+mentioned in the release notes for the affected release.
+EOF
+    'Private' => <<EOF
+An interface that can be used within the GNOME stack itself, but that is not
+documented for end-users.  Such functions should only be used in specified and
+documented ways.
+EOF
 );
 
 # Elements to consider non-block items in MarkDown parsing
@@ -1239,7 +1269,7 @@ $header
   <title>Annotation Glossary</title>
 EOF
 
-    foreach my $annotation (sort(keys(%AnnotationsUsed))) {
+    foreach my $annotation (sort({lc $a cmp lc $b} keys(%AnnotationsUsed))) {
         if(defined($AnnotationDefinition{$annotation})) {
             my $def = $AnnotationDefinition{$annotation};
             my $curletter = uc(substr($annotation,0,1));
@@ -1381,7 +1411,9 @@ sub OutputSymbolTraits {
         $desc .= "<para role=\"since\">Since $Since{$symbol}</para>";
     }
     if (exists $StabilityLevel{$symbol}) {
-        $desc .= "<para role=\"stability\">Stability Level: $StabilityLevel{$symbol}</para>";
+        my $stability = $StabilityLevel{$symbol};
+        $AnnotationsUsed{$stability} = 1;
+        $desc .= "<para role=\"stability\">Stability Level: <acronym>$stability</acronym></para>";
     }
     return $desc;
 }
@@ -2447,9 +2479,11 @@ sub OutputSGMLFile {
         #print "Found stability: $stability";
     }
     if ($stability) {
-        $stability = "<refsect1 id=\"$section_id.stability-level\">\n<title>Stability 
Level</title>\n$stability, unless otherwise indicated\n</refsect1>\n";
+        $AnnotationsUsed{$stability} = 1;
+        $stability = "<refsect1 id=\"$section_id.stability-level\">\n<title>Stability 
Level</title>\n<acronym>$stability</acronym>, unless otherwise indicated\n</refsect1>\n";
     } elsif ($DEFAULT_STABILITY) {
-        $stability = "<refsect1 id=\"$section_id.stability-level\">\n<title>Stability 
Level</title>\n$DEFAULT_STABILITY, unless otherwise indicated\n</refsect1>\n";
+        $AnnotationsUsed{$DEFAULT_STABILITY} = 1;
+        $stability = "<refsect1 id=\"$section_id.stability-level\">\n<title>Stability 
Level</title>\n<acronym>$DEFAULT_STABILITY</acronym>, unless otherwise indicated\n</refsect1>\n";
     }
 
     my $image = $SymbolDocs{"$TMPL_DIR/$file:Image"};
diff --git a/style/style.css b/style/style.css
index 705a5c9..44c3063 100644
--- a/style/style.css
+++ b/style/style.css
@@ -404,6 +404,11 @@ h2 .extralinks, h3 .extralinks
   font-weight: normal;
 }
 
+acronym,abbr 
+{
+  border-bottom: 1px dotted gray;
+}
+
 /* code listings */
 
 .listing_code .programlisting .cbracket   { color: #a40000; } /* tango: scarlet red 3 */
diff --git a/tests/annotations/docs/tester-sections.txt b/tests/annotations/docs/tester-sections.txt
index 59fef69..239ed1d 100644
--- a/tests/annotations/docs/tester-sections.txt
+++ b/tests/annotations/docs/tester-sections.txt
@@ -12,6 +12,7 @@ annotation_skip
 annotation_skip_return
 annotation_scope
 annotation_rename_to
+stability_unstable
 <SUBSECTION Standard>
 <SUBSECTION Private>
 </SECTION>
diff --git a/tests/annotations/src/tester.c b/tests/annotations/src/tester.c
index 09f103a..d731a61 100644
--- a/tests/annotations/src/tester.c
+++ b/tests/annotations/src/tester.c
@@ -1,6 +1,7 @@
 /**
  * SECTION:tester
  * @short_description: module for gtk-doc unit test
+ * @stability: stable
  *
  * This file contains non-sense code for the sole purpose of testing the docs.
  */
@@ -145,3 +146,16 @@ void
 annotation_rename_to (void)
 {
 }
+
+/**
+ * stability_unstable:
+ *
+ * An experimental function.
+ *
+ * Stability: unstable
+ */
+void
+stability_unstable(void)
+{
+}
+
diff --git a/tests/annotations/src/tester.h b/tests/annotations/src/tester.h
index 3baf440..612b4d9 100644
--- a/tests/annotations/src/tester.h
+++ b/tests/annotations/src/tester.h
@@ -14,22 +14,24 @@ struct _GtkdocAnnotation {
   gpointer that;
 };
 
-extern void annotation_array_length (GObject *list, gint n_columns, GType *types);
+void annotation_array_length (GObject *list, gint n_columns, GType *types);
 
-extern gchar * annotation_nullable (const gchar *uri, const gchar *label);
+gchar * annotation_nullable (const gchar *uri, const gchar *label);
 
-extern gboolean annotation_elementtype (const GList *list);
-extern gboolean annotation_elementtype_transfer (const GList *list);
-extern GList *annotation_elementtype_returns (void);
+gboolean annotation_elementtype (const GList *list);
+gboolean annotation_elementtype_transfer (const GList *list);
+GList *annotation_elementtype_returns (void);
 
-extern gboolean annotation_outparams (GList **list);
+gboolean annotation_outparams (GList **list);
 
-extern void annotation_skip (GList *list);
-extern gboolean annotation_skip_return (GList *list);
+void annotation_skip (GList *list);
+gboolean annotation_skip_return (GList *list);
 
-extern void annotation_scope (GCallback *callback, gpointer user_data);
+void annotation_scope (GCallback *callback, gpointer user_data);
 
-extern void annotation_rename_to (void);
+void annotation_rename_to (void);
+
+void stability_unstable(void);
 
 #endif // GTKDOC_TESTER_H