[gnome-devel-docs] programming-guidelines: Move documentation section to its own page

[Philip Withnall <pwithnall src gnome org>]

commit 891d151b919acfb904c7b53cbca806ce83129652
Author: Philip Withnall <philip withnall collabora co uk>
Date:   Tue Feb 3 10:09:19 2015 +0000

    programming-guidelines: Move documentation section to its own page
    
    It isn’t really anything to do with C coding style, and can be expanded.
    
    https://bugzilla.gnome.org/show_bug.cgi?id=376123

 programming-guidelines/C/c-coding-style.page |   77 --------------------
 programming-guidelines/C/documentation.page  |  100 ++++++++++++++++++++++++++
 programming-guidelines/Makefile.am           |    4 +-
 3 files changed, 103 insertions(+), 78 deletions(-)
---
diff --git a/programming-guidelines/C/c-coding-style.page b/programming-guidelines/C/c-coding-style.page
index 3fe16e3..66bbaca 100644
--- a/programming-guidelines/C/c-coding-style.page
+++ b/programming-guidelines/C/c-coding-style.page
@@ -937,81 +937,4 @@ typedef struct _GtkFooInterface         GtkFooInterface;
       should be declared static.
     </p>
   </section>
-
-  <section id="documentation">
-    <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.  A lot of
-      GNOME's infrastructure is built to handle with documentation
-      written using gtk-doc.
-    </p>
-
-    <p>
-      All public APIs must have gtk-doc comments. For functions, these should
-      be placed in the source file, directly above the function.
-    </p>
-
-    <code>
-/* valid */
-/**
- * gtk_get_flow:
- * @widget: a #GtkWidget
- *
- * Gets the flow of a widget.
- *
- * Note that flows may be laminar or turbulent...
- *
- * Returns: (transfer none): the flow of @widget
- */
-GtkFlow *
-gtk_get_flow (GtkWidget *widget)
-{
-
-  ...
-
-}
-    </code>
-
-    <p>
-      Documentation comments for macros, function types, class
-      structs, etc. should be placed next to the definitions, typically
-      in header files.
-    </p>
-
-    <p>
-      Section introductions should be placed in the source file they describe,
-      after the license header:
-    </p>
-
-    <code>
-/* valid */
-/**
- * SECTION:gtksizerequest
- * @Short_Description: Height-for-width geometry management
- * @Title: GtkSizeRequest
- *
- * The GtkSizeRequest interface is GTK+'s height-for-width (and
- * width-for-height) geometry management system.
- * ...
- */
-    </code>
-
-    <p>
-      Keep in mind that in order to include a function, macro,
-      function type, or struct type, it needs to be listed in your
-      documentation's modulename-sections.txt file.
-    </p>
-
-    <p>
-      To properly document a new class, it needs to be given its own
-      section in modulename-sections.txt, needs to be included in your
-      toplevel modulename-docs.sgml, and the get_type() function for
-      your class needs to listed in your modulename.types.
-    </p>
-  </section>
-
 </page>
diff --git a/programming-guidelines/C/documentation.page b/programming-guidelines/C/documentation.page
new file mode 100644
index 0000000..393c65d
--- /dev/null
+++ b/programming-guidelines/C/documentation.page
@@ -0,0 +1,100 @@
+<page xmlns="http://projectmallard.org/1.0/";
+      xmlns:its="http://www.w3.org/2005/11/its";
+      type="guide" style="task"
+      id="documentation">
+
+  <info>
+    <link type="guide" xref="index#coding-style"/>
+
+    <credit type="author copyright">
+      <name>Federico Mena-Quintero</name>
+      <email its:translate="no">federico gnome org</email>
+      <years>2013</years>
+    </credit>
+    <credit type="author copyright">
+      <name>The GTK+ Team</name>
+    </credit>
+
+    <include href="cc-by-sa-3-0.xml" xmlns="http://www.w3.org/2001/XInclude"/>
+
+    <desc>Adding documentation to libraries and APIs</desc>
+  </info>
+
+  <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.  A lot of
+    GNOME's infrastructure is built to handle with documentation
+    written using gtk-doc.
+  </p>
+
+  <section id="public-api">
+    <title>Public APIs</title>
+
+    <p>
+      All public APIs must have gtk-doc comments. For functions, these should
+      be placed in the source file, directly above the function.
+    </p>
+
+    <code>
+/* valid */
+/**
+ * gtk_get_flow:
+ * @widget: a #GtkWidget
+ *
+ * Gets the flow of a widget.
+ *
+ * Note that flows may be laminar or turbulent...
+ *
+ * Returns: (transfer none): the flow of @widget
+ */
+GtkFlow *
+gtk_get_flow (GtkWidget *widget)
+{
+
+  ...
+
+}
+    </code>
+
+    <p>
+      Documentation comments for macros, function types, class
+      structs, etc. should be placed next to the definitions, typically
+      in header files.
+    </p>
+
+    <p>
+      Section introductions should be placed in the source file they describe,
+      after the license header:
+    </p>
+
+    <code>
+/* valid */
+/**
+ * SECTION:gtksizerequest
+ * @Short_Description: Height-for-width geometry management
+ * @Title: GtkSizeRequest
+ *
+ * The GtkSizeRequest interface is GTK+'s height-for-width (and
+ * width-for-height) geometry management system.
+ * ...
+ */
+    </code>
+
+    <p>
+      Keep in mind that in order to include a function, macro,
+      function type, or struct type, it needs to be listed in your
+      documentation's modulename-sections.txt file.
+    </p>
+
+    <p>
+      To properly document a new class, it needs to be given its own
+      section in modulename-sections.txt, needs to be included in your
+      toplevel modulename-docs.sgml, and the get_type() function for
+      your class needs to listed in your modulename.types.
+    </p>
+  </section>
+</page>
diff --git a/programming-guidelines/Makefile.am b/programming-guidelines/Makefile.am
index 219c965..5c8ef81 100644
--- a/programming-guidelines/Makefile.am
+++ b/programming-guidelines/Makefile.am
@@ -8,7 +8,9 @@ HELP_EXTRA = \
 HELP_FILES = \
        additional-materials.page \
        c-coding-style.page \
+       documentation.page \
        index.page \
-       writing-good-code.page
+       writing-good-code.page \
+       $(NULL)
 
 HELP_LINGUAS =