From: Tiago Vignatti <tiago.vignatti@intel.com>
Date: Fri, 9 Nov 2012 22:14:31 +0000 (-0200)
Subject: doc: Auto-generate API methods and classes documentation
X-Git-Tag: submit/2.0alpha-wayland/20121121.142951~18
X-Git-Url: http://review.tizen.org/git/?a=commitdiff_plain;h=c77ba6bebc181d88851d802907b0016fd4f810fc;p=profile%2Fivi%2Fwayland.git

doc: Auto-generate API methods and classes documentation

There's work to do still for giving a prettier style on the documentation, for
instance splitting paragraphs correctly and printing the detailed description
of the methods as well.

Signed-off-by: Tiago Vignatti <tiago.vignatti@intel.com>
---

diff --git a/doc/Wayland/Makefile.am b/doc/Wayland/Makefile.am
index 4a7f2cd..71ae9b8 100644
--- a/doc/Wayland/Makefile.am
+++ b/doc/Wayland/Makefile.am
@@ -32,10 +32,20 @@ en-US/ProtocolInterfaces.xml: $(top_srcdir)/protocol/wayland.xml $(srcdir)/proto
 	$(AM_V_GEN)$(XSLTPROC) $(srcdir)/protocol-interfaces-to-docbook.xsl \
 		$(top_srcdir)/protocol/wayland.xml > en-US/ProtocolInterfaces.xml
 
-en-US/WaylandClientAPI.xml: $(top_builddir)/doc/doxygen/xml/wayland-client_8h.xml $(srcdir)/doxygen-to-publican.xsl
+# WaylandClientAPI.xml is generated after combining all xml in one single file
+# with the exception of wayland-client_8h.xml that is omitted to not duplicate
+# the output methods.
+en-US/WaylandClientAPI.xml: $(top_builddir)/doc/doxygen/xml/index.xml $(srcdir)/doxygen-to-publican.xsl
 	$(AM_V_GEN)$(MKDIR_P) en-US/images
+	$(AM_V_GEN)mv $(top_srcdir)/doc/doxygen/xml/wayland-client_8h.xml \
+		$(top_srcdir)/doc/doxygen/
+	$(AM_V_GEN)$(XSLTPROC) $(top_srcdir)/doc/doxygen/xml/combine.xslt \
+		$(top_srcdir)/doc/doxygen/xml/index.xml > \
+		$(top_srcdir)/doc/doxygen/xml/clientAPI.xml
+	$(AM_V_GEN)mv $(top_srcdir)/doc/doxygen/wayland-client_8h.xml \
+		$(top_srcdir)/doc/doxygen/xml
 	$(AM_V_GEN)$(XSLTPROC) $(srcdir)/doxygen-to-publican.xsl \
-		$(top_builddir)/doc/doxygen/xml/wayland-client_8h.xml > en-US/WaylandClientAPI.xml
+		$(top_builddir)/doc/doxygen/xml/clientAPI.xml > en-US/WaylandClientAPI.xml
 
 # Copy the en_US source files into en-US destination
 # This is required for out-of-source-tree build as publican does not allow us
diff --git a/doc/Wayland/doxygen-to-publican.xsl b/doc/Wayland/doxygen-to-publican.xsl
index bd1f5a4..3ddcbd3 100644
--- a/doc/Wayland/doxygen-to-publican.xsl
+++ b/doc/Wayland/doxygen-to-publican.xsl
@@ -13,7 +13,7 @@
 
   <section id="sect-Library-Client">
     <title>Client API</title>
-    <para>Following is the Wayland library interface for clients
+    <para>Following is the Wayland library classes for clients
 	  (<emphasis>libwayland-client</emphasis>). Note that most of the
 	  procedures are related with IPC, which is the main responsibility of
 	  the library.
@@ -21,26 +21,52 @@
 
     <para>
     <variablelist>
+    <xsl:apply-templates select="/doxygen/compounddef" />
+    </variablelist>
+    </para>
+
+    <para>And methods for the respective classes.</para>
+
+    <para>
+    <variablelist>
     <xsl:apply-templates select="/doxygen/compounddef/sectiondef/memberdef" />
     </variablelist>
     </para>
   </section>
 </xsl:template>
 
-<xsl:template match="memberdef" >
-    <xsl:if test="@kind = 'function'">
-  <varlistentry>
 
-      <term>
-      <xsl:value-of select="name" />
-      </term>
-    <listitem>
-    <para>
-      <xsl:value-of select="briefdescription" />
-    </para>
-    </listitem>
-  </varlistentry>
-  </xsl:if>
+<!-- methods -->
+<xsl:template match="memberdef" >
+    <xsl:if test="@kind = 'function' and @static = 'no'">
+    <varlistentry>
+        <term>
+        <xsl:value-of select="name" />
+        - <xsl:value-of select="briefdescription" />
+        </term>
+        <listitem>
+            <para></para>
+        </listitem>
+    </varlistentry>
+    </xsl:if>
 </xsl:template>
 
+<!-- classes -->
+<xsl:template match="compounddef" >
+    <xsl:if test="@kind = 'class' ">
+    <varlistentry>
+        <term>
+            <xsl:value-of select="compoundname" />
+            <xsl:if test="briefdescription">
+                - <xsl:value-of select="briefdescription" />
+            </xsl:if>
+        </term>
+
+        <!-- TODO: the output text is not splitting paragraphs correctly -->
+        <listitem>
+            <para><xsl:value-of select="detaileddescription"/></para>
+        </listitem>
+    </varlistentry>
+    </xsl:if>
+</xsl:template>
 </xsl:stylesheet>