Generate gtk-doc files and add some gtk-doc markup

7 files changed, 213 insertions, 0 deletions

diff --git a/docs/Makefile.am b/docs/Makefile.am
new file mode 100644
index 0000000..aabe0d2
--- /dev/null
+++ b/docs/Makefile.am
@@ -0,0 +1,5 @@
+SUBDIRS = 						\
+	api
+
+
+-include $(top_srcdir)/git.mk
diff --git a/docs/api/Makefile.am b/docs/api/Makefile.am
new file mode 100644
index 0000000..7aafad6
--- /dev/null
+++ b/docs/api/Makefile.am
@@ -0,0 +1,92 @@
+## Process this file with automake to produce Makefile.in
+
+NULL =
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=gusb
+
+# The top-level SGML file.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.sgml
+
+# The directory containing the source code. Relative to $(srcdir).
+# gtk-doc will search all .c & .h files beneath here for inline comments
+# documenting the functions and macros.
+DOC_SOURCE_DIR=../../libgusb
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS=
+
+# Extra options to supply to gtkdoc-scan.
+SCAN_OPTIONS=
+
+# Extra options to supply to gtkdoc-mkdb.
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+MKTMPL_OPTIONS=
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+HFILE_GLOB=$(top_srcdir)/libgusb/gusb-*.h
+CFILE_GLOB=$(top_srcdir)/libgusb/gusb-*.c
+
+# Header files to ignore when scanning.
+IGNORE_HFILES =						\
+	config.h					\
+	gusb-marshal.h					\
+	$(NULL)
+
+# Images to copy into HTML directory.
+#HTML_IMAGES =						\
+#	spec/pk-transactions-success.png		\
+#	spec/pk-transactions-trusted.png
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+content_files =						\
+	version.xml					\
+	$(NULL)
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+expand_content_files=
+
+# CFLAGS and LDFLAGS for compiling gtkdoc-scangobj with your library.
+# Only needed if you are using gtkdoc-scangobj to dynamically query widget
+# signals and properties.
+INCLUDES =						\
+	$(GLIB_CFLAGS)					\
+	-I$(top_builddir)/libgusb			\
+	-I$(top_srcdir)/libgusb				\
+	$(NULL)
+
+GUSB_LIBS = $(top_builddir)/libgusb/libgusb.la
+
+GTKDOC_LIBS =						\
+	$(GLIB_LIBS)					\
+	$(GUSB_LIBS)					\
+	$(USB_LIBS)					\
+	$(NULL)
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+CLEANFILES +=						\
+	*.txt						\
+	*.types						\
+	*.args						\
+	*.hierarchy					\
+	*.interfaces					\
+	*.prerequisites					\
+	*.signals					\
+	*.stamp						\
+	tmpl
+
+# Other files to distribute
+EXTRA_DIST += version.xml.in
+
+-include $(top_srcdir)/git.mk
diff --git a/docs/api/clean.sh b/docs/api/clean.sh
new file mode 100755
index 0000000..c335583
--- /dev/null
+++ b/docs/api/clean.sh
@@ -0,0 +1,7 @@
+rm -f *.txt
+rm -f *-scan.*
+rm -f *.types
+rm -f html/*
+rm -f tmpl/*
+rm -f xml/*
+
diff --git a/docs/api/gusb-docs.sgml b/docs/api/gusb-docs.sgml
new file mode 100644
index 0000000..3189c57
--- /dev/null
+++ b/docs/api/gusb-docs.sgml
@@ -0,0 +1,74 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+               "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
+<!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
+  <bookinfo>
+    <title>GUsb Reference Manual</title>
+    <releaseinfo>
+      for GUsb &version;
+    </releaseinfo>
+    <authorgroup>
+      <author>
+        <firstname>Richard</firstname>
+        <surname>Hughes</surname>
+        <affiliation>
+          <address>
+            <email>richard@hughsie.com</email>
+          </address>
+        </affiliation>
+      </author>
+    </authorgroup>
+    <copyright>
+      <year>2011</year>
+      <holder>Richard Hughes</holder>
+    </copyright>
+  </bookinfo>
+
+  <reference id="specification">
+    <title>GUSB Specification</title>
+    <partintro>
+      <para>
+        GUsb is a GLib wrapper for libusb1.
+      </para>
+      <para>
+        This manual documents features of GUsb.
+      </para>
+    </partintro>
+    <xi:include href="spec/gusb-introduction.xml"/>
+  </reference>
+
+  <reference id="libgusb">
+    <title>libgusb GObject library</title>
+    <partintro>
+      <para>
+        This part documents GObjects used in libgusb.
+      </para>
+    </partintro>
+    <xi:include href="xml/gusb-context.xml"/>
+    <xi:include href="xml/gusb-source.xml"/>
+  </reference>
+
+  <reference id="libgusb-helpers">
+    <title>libgusb glib helpers</title>
+    <partintro>
+      <para>
+        This part documents helper funtions in libgusb.
+      </para>
+    </partintro>
+    <xi:include href="xml/gusb-version.xml"/>
+  </reference>
+
+  <reference id="faq">
+    <title>Frequently asked questions</title>
+    <partintro>
+      <para>
+        This part has answers to developer frequently asked questions.
+      </para>
+    </partintro>
+    <xi:include href="spec/gusb-faq.xml"/>
+  </reference>
+
+</book>
+
diff --git a/docs/api/spec/gusb-faq.xml b/docs/api/spec/gusb-faq.xml
new file mode 100644
index 0000000..755dd87
--- /dev/null
+++ b/docs/api/spec/gusb-faq.xml
@@ -0,0 +1,19 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+
+<chapter id="faq">
+  <title>FAQ</title>
+  <para>
+    The following sections explain frequently asked questions from people.
+  </para>
+
+  <sect1 id="faq-why">
+    <title>Why wrap libusb1?</title>
+    <para>
+      libusb1 is a pain in the arse to use in GLib.
+    </para>
+
+  </sect1>
+
+</chapter>
+
diff --git a/docs/api/spec/gusb-introduction.xml b/docs/api/spec/gusb-introduction.xml
new file mode 100644
index 0000000..7f16b64
--- /dev/null
+++ b/docs/api/spec/gusb-introduction.xml
@@ -0,0 +1,15 @@
+<?xml version="1.0" encoding="ISO-8859-1"?>
+<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd">
+
+<chapter id="introduction">
+  <title>GUSB Introduction</title>
+
+  <sect1 id="introduction-description">
+    <title>Overall Description</title>
+    <para>
+      GUsb is a GLib wrapper for libusb1.
+    </para>
+  </sect1>
+
+</chapter>
+
diff --git a/docs/api/version.xml.in b/docs/api/version.xml.in
new file mode 100644
index 0000000..d78bda9
--- /dev/null
+++ b/docs/api/version.xml.in
@@ -0,0 +1 @@
+@VERSION@