[gnome-devel-docs] programming-guidelines: Add a synopsis to the documentation page

[Philip Withnall <pwithnall src gnome org>]

commit a93c45816eddb17b97b3ae71100198f0b053ea37
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Tue Feb 3 14:05:40 2015 +0000

    programming-guidelines: Add a synopsis to the documentation page
    
    https://bugzilla.gnome.org/show_bug.cgi?id=376123

 programming-guidelines/C/documentation.page |   58 ++++++++++++++++++++++-----
 1 files changed, 48 insertions(+), 10 deletions(-)
---
diff --git a/programming-guidelines/C/documentation.page b/programming-guidelines/C/documentation.page
index 0a20303..c9eff4f 100644
--- a/programming-guidelines/C/documentation.page
+++ b/programming-guidelines/C/documentation.page
@@ -28,16 +28,54 @@
 
   <title>Documentation</title>
 
-  <p>
-    The preferred documentation system for GNOME libraries is <link
-    xref="http://www.gtk.org/gtk-doc/";>gtk-doc</link>, which
-    extracts inline comments from the code to let you build a <link
-    xref="http://docbook.org/";>DocBook</link> document and collection of HTML
-    pages.  These can then be read in
-    <link xref="https://wiki.gnome.org/Apps/Devhelp";>Devhelp</link>.  A lot of
-    GNOME’s infrastructure is built to handle with documentation written using
-    gtk-doc.
-  </p>
+  <synopsis>
+    <title>Summary</title>
+
+    <list>
+      <item><p>
+        Use gtk-doc with up-to-date settings for API documentation.
+        (<link xref="#gtk-doc"/>)
+      </p></item>
+      <item><p>
+        Use XML entities for including external symbols into the documentation.
+        (<link xref="#build-system"/>)
+      </p></item>
+      <item><p>
+        Use a consistent, standard, table of contents for all API documentation
+        to maintain familiarity. (<link xref="#standard-layout"/>)
+      </p></item>
+      <item><p>
+        Use <cmd>gdbus-codegen</cmd> to generate D-Bus API documentation to
+        include in the gtk-doc build. (<link xref="#dbus-api"/>)
+      </p></item>
+      <item><p>
+        Add introspection annotations to all API documentation.
+        (<link xref="#introspection-annotations"/>)
+      </p></item>
+      <item><p>
+        Add <code>Since</code> lines to all API documentation.
+        (<link xref="#symbol-versioning"/>)
+      </p></item>
+      <item><p>
+        Enable gtk-doc tests. (<link xref="#keeping-up-to-date"/>)
+      </p></item>
+    </list>
+  </synopsis>
+
+  <section id="gtk-doc">
+    <title>gtk-doc</title>
+
+    <p>
+      The preferred documentation system for GNOME libraries is <link
+      xref="http://www.gtk.org/gtk-doc/";>gtk-doc</link>, which
+      extracts inline comments from the code to let you build a <link
+      xref="http://docbook.org/";>DocBook</link> document and collection of HTML
+      pages.  These can then be read in
+      <link xref="https://wiki.gnome.org/Apps/Devhelp";>Devhelp</link>.  A lot of
+      GNOME’s infrastructure is built to handle with documentation written using
+      gtk-doc.
+    </p>
+  </section>
 
   <section id="build-system">
     <title>Build System</title>