Add gtk-doc support

Yes, it's really me.  Colin Walters.  Writing documentation.  You
don't need to do a DNA test.

Makefile-libostree-defines.am

@@ -0,0 +1,29 @@
+# Shared variables between toplevel Makefile.am and doc/Makefile.am
+# ...since gtk-doc forces use of recursive make =(
+#
+# Copyright (C) 2013 Colin Walters <walters@verbum.org>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the
+# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+libostree_public_headers = \
+	src/libostree/ostree.h \
+	src/libostree/ostree-core.h \
+	src/libostree/ostree-mutable-tree.h \
+	src/libostree/ostree-repo.h \
+	src/libostree/ostree-types.h \
+	src/libostree/ostree-repo-file.h \
+	src/libostree/ostree-diff.h \
+	$(NULL)

Makefile-libostree.am

@@ -17,18 +17,12 @@
 # Free Software Foundation, Inc., 59 Temple Place - Suite 330,
 # Boston, MA 02111-1307, USA.
 
+include Makefile-libostree-defines.am
+
 lib_LTLIBRARIES += libostree-1.la
 
 libostreeheadersdir = $(includedir)/ostree-1
-libostreeheaders_DATA = \
+libostreeheaders_DATA = $(libostree_public_headers)
-	src/libostree/ostree.h \
-	src/libostree/ostree-core.h \
-	src/libostree/ostree-mutable-tree.h \
-	src/libostree/ostree-repo.h \
-	src/libostree/ostree-types.h \
-	src/libostree/ostree-repo-file.h \
-	src/libostree/ostree-diff.h \
-	$(NULL)
 
 libostree_1_la_SOURCES = \
 	src/libostree/ostree-core.c \

Makefile.am

@@ -22,12 +22,20 @@ AM_CPPFLAGS = -DDATADIR='"$(datadir)"' -DLIBEXECDIR='"$(libexecdir)"' \
 	-DSOUP_VERSION_MIN_REQUIRED=SOUP_VERSION_2_40 -DSOUP_VERSION_MAX_ALLOWED=SOUP_VERSION_40
 AM_CFLAGS = $(WARN_CFLAGS)
 
+# Subdirectories
+SUBDIRS =
+
 if BUILD_EMBEDDED_DEPENDENCIES
-SUBDIRS = embedded-dependencies .
+SUBDIRS += embedded-dependencies
-else
-SUBDIRS = .
 endif
 
+SUBDIRS += .
+
+if BUILD_DOCUMENTATION
+SUBDIRS += doc
+endif
+
+# Common variables
 NULL = 
 INSTALL_DATA_HOOKS =
 BUILT_SOURCES =
@@ -103,44 +111,6 @@ include Makefile-dracut.am
 
 install-data-hook: $(INSTALL_DATA_HOOKS)
 
-#  Docbook generation copied from systemd/Makefile.am
-#
-#  Copyright 2010 Lennart Poettering
-#
-#  systemd is free software; you can redistribute it and/or modify it
-#  under the terms of the GNU General Public License as published by
-#  the Free Software Foundation; either version 2 of the License, or
-#  (at your option) any later version.
-#
-#  systemd is distributed in the hope that it will be useful, but
-#  WITHOUT ANY WARRANTY; without even the implied warranty of
-#  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
-#  General Public License for more details.
-#
-#  You should have received a copy of the GNU General Public License
-#  along with systemd; If not, see <http://www.gnu.org/licenses/>.
-
-XML_FILES = \
-	${patsubst %.1,%.xml,${patsubst %.3,%.xml,${patsubst %.5,%.xml,${patsubst %.7,%.xml,${patsubst %.8,%.xml,$(MANPAGES)}}}}}
-EXTRA_DIST += $(XML_FILES)
-
-if BUILD_DOCUMENTATION
-
-dist_man_MANS = $(MANPAGES)
-
-XSLTPROC_FLAGS = \
-	--nonet \
-	--param funcsynopsis.style "'ansi'"
-
-XSLTPROC_PROCESS_MAN = \
-	$(AM_V_GEN)$(MKDIR_P) $(dir $@) && \
-	$(XSLTPROC) -o $@ $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl $<
-
-doc/%.1: doc/%.xml
-	$(XSLTPROC_PROCESS_MAN)
-
-endif
-
 
 release-tag:
 	git tag -m "Release $(VERSION)" v$(VERSION)

autogen.sh

@@ -24,6 +24,18 @@ then
   git submodule update
 fi
 
+GTKDOCIZE=$(which gtkdocize 2>/dev/null)
+if test -z $GTKDOCIZE; then
+        echo "You don't have gtk-doc installed, and thus won't be able to generate the documentation."
+        rm -f gtk-doc.make
+        cat > gtk-doc.make <<EOF
+EXTRA_DIST =
+CLEANFILES =
+EOF
+else
+        gtkdocize || exit $?
+fi
+
 autoreconf --force --install --verbose
 
 cd $olddir

configure.ac

@@ -92,6 +92,7 @@ AS_IF([test x$enable_documentation = xyes], [
    AS_IF([test x$XSLTPROC = x], [
       AC_MSG_ERROR([xsltproc is required to build documentation])
    ])
+GTK_DOC_CHECK([1.15], [--flavour no-tmpl])
 ])
 AM_CONDITIONAL(BUILD_DOCUMENTATION, test x$enable_documentation = xyes)
 
@@ -136,6 +137,7 @@ AS_IF([test "x$with_dracut" = "xyes"], [
 AC_CONFIG_FILES([
 Makefile
 embedded-dependencies/Makefile
+doc/Makefile
 src/libostree/ostree-1.pc
 ])
 AC_OUTPUT

doc/Makefile.am

@@ -0,0 +1,134 @@
+# Copyright (C) 2013 Colin Walters <walters@verbum.org>
+#
+# This library is free software; you can redistribute it and/or
+# modify it under the terms of the GNU Lesser General Public
+# License as published by the Free Software Foundation; either
+# version 2 of the License, or (at your option) any later version.
+#
+# This library is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+# Lesser General Public License for more details.
+#
+# You should have received a copy of the GNU Lesser General Public
+# License along with this library; if not, write to the
+# Free Software Foundation, Inc., 59 Temple Place - Suite 330,
+# Boston, MA 02111-1307, USA.
+
+abs_top_builddir = @abs_top_builddir@
+
+include ../Makefile-libostree-defines.am
+
+NULL =
+
+# We require automake 1.6 at least.
+AUTOMAKE_OPTIONS = 1.6
+
+# The name of the module, e.g. 'glib'.
+DOC_MODULE=libostree
+
+# The top-level SGML file. You can change this if you want to.
+DOC_MAIN_SGML_FILE=$(DOC_MODULE)-docs.xml
+
+# 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.
+# e.g. DOC_SOURCE_DIR=../../../gtk
+DOC_SOURCE_DIR=$(top_srcdir)/src
+
+# Extra options to pass to gtkdoc-scangobj. Not normally needed.
+SCANGOBJ_OPTIONS= --version
+
+# Extra options to supply to gtkdoc-scan.
+# e.g. SCAN_OPTIONS=--deprecated-guards="GTK_DISABLE_DEPRECATED"
+SCAN_OPTIONS= --rebuild-types
+
+# Extra options to supply to gtkdoc-mkdb.
+# e.g. MKDB_OPTIONS=--sgml-mode --output-format=xml
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+# e.g. MKTMPL_OPTIONS=--only-section-tmpl
+MKTMPL_OPTIONS=
+
+# MKHTML_OPTIONS=--path="$(builddir)/html $(srcdir)/html"
+
+# Extra options to supply to gtkdoc-fixref. Not normally needed.
+# e.g. FIXXREF_OPTIONS=--extra-dir=../gdk-pixbuf/html --extra-dir=../gdk/html
+FIXXREF_OPTIONS=
+
+# Used for dependencies. The docs will be rebuilt if any of these change.
+# e.g. HFILE_GLOB=$(top_srcdir)/gtk/*.h
+# e.g. CFILE_GLOB=$(top_srcdir)/gtk/*.c
+HFILE_GLOB=$(addprefix $(top_srcdir)/,$(libostree_public_headers))
+CFILE_GLOB=$(top_srcdir)/src/libostree/*.c
+
+# Header files to ignore when scanning.
+# e.g. IGNORE_HFILES=gtkdebug.h gtkintl.h
+IGNORE_HFILES= $(NULL)
+
+# Images to copy into HTML directory.
+# e.g. HTML_IMAGES=$(top_srcdir)/gtk/stock-icons/stock_about_24.png
+HTML_IMAGES=
+
+# Extra SGML files that are included by $(DOC_MAIN_SGML_FILE).
+# e.g. content_files=running.sgml building.sgml changes-2.0.sgml
+content_files=$(NULL)
+
+# SGML files where gtk-doc abbrevations (#GtkWidget) are expanded
+# These files must be listed here *and* in content_files
+# e.g. expand_content_files=running.sgml
+expand_content_files= \
+	version.xml \
+	$(NULL)
+
+# 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.
+# e.g. INCLUDES=-I$(top_srcdir) -I$(top_builddir) $(GTK_DEBUG_FLAGS)
+# e.g. GTKDOC_LIBS=$(top_builddir)/gtk/$(gtktargetlib)
+GTKDOC_LIBS=
+
+# Hacks around gtk-doc brokenness for out of tree builds
+libostree-sections.txt: $(srcdir)/libostree-sections.txt
+	cp $< $@
+
+version.xml:
+	echo -n $(VERSION) > "$@"
+
+# This includes the standard gtk-doc make rules, copied by gtkdocize.
+include $(top_srcdir)/gtk-doc.make
+
+man1_MANS =
+
+if ENABLE_GTK_DOC
+man1_MANS += ostree.1
+
+XSLTPROC_FLAGS = \
+        --nonet \
+        --stringparam man.output.quietly 1 \
+        --stringparam funcsynopsis.style ansi \
+        --stringparam man.th.extra1.suppress 1 \
+        --stringparam man.authors.section.enabled 0 \
+        --stringparam man.copyright.section.enabled 0
+
+XSLTPROC_MAN = \
+	$(XSLTPROC) $(XSLTPROC_FLAGS) http://docbook.sourceforge.net/release/xsl/current/manpages/docbook.xsl
+
+.xml.1:
+	$(AM_V_GEN) $(XSLTPROC_MAN) $<
+
+endif # ENABLE_GTK_DOC
+
+MAN_IN_FILES = \
+	$(man1_MANS:.1=.xml) \
+	$(NULL)
+
+CLEANFILES += \
+	$(man1_MANS) \
+	$(NULL)
+
+EXTRA_DIST += \
+	$(MAN_IN_FILES) \
+	version.xml \
+	$(NULL)

doc/libostree-docs.xml

@@ -0,0 +1,24 @@
+<?xml version="1.0"?>
+<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.3//EN"
+               "http://www.oasis-open.org/docbook/xml/4.3/docbookx.dtd"
+[
+  <!ENTITY % local.common.attrib "xmlns:xi  CDATA  #FIXED 'http://www.w3.org/2003/XInclude'">
+  <!ENTITY version SYSTEM "version.xml">
+]>
+<book id="index">
+	<bookinfo>
+		<title>libostree</title>
+		<releaseinfo>for OSTree &version;</releaseinfo>
+	</bookinfo>
+
+	<chapter xml:id="reference">
+		<title>API Reference</title>
+		<xi:include href="xml/libostree-core.xml"/>
+
+		<index id="api-index-full">
+			<title>API Index</title>
+			<xi:include href="xml/api-index-full.xml"><xi:fallback /></xi:include>
+		</index>
+
+	</chapter>
+</book>

doc/libostree-sections.txt

@@ -0,0 +1,18 @@
+<SECTION>
+<FILE>libostree-core</FILE>
+OSTREE_MAX_METADATA_SIZE
+OSTREE_MAX_RECURSION
+OSTREE_EMPTY_STRING_SHA256
+OstreeObjectType
+OSTREE_OBJECT_TYPE_IS_META
+OSTREE_OBJECT_TYPE_LAST
+OSTREE_FILE_HEADER_GVARIANT_FORMAT
+OSTREE_DIRMETA_GVARIANT_FORMAT
+OSTREE_TREE_GVARIANT_FORMAT
+OSTREE_COMMIT_GVARIANT_FORMAT
+OSTREE_ZLIB_FILE_HEADER_GVARIANT_FORMAT
+ostree_metadata_variant_type
+ostree_validate_checksum_string
+ostree_checksum_to_bytes
+ostree_checksum_to_bytes_v
+</SECTION>

src/libostree/ostree-core.c

@@ -36,11 +36,15 @@
   (( ((unsigned long)(this)) + (((unsigned long)(boundary)) -1)) & (~(((unsigned long)(boundary))-1)))
 
 /**
- * ostree_metadata_variant_type:
+ * SECTION:libostree-core
- * @objtype: an object type
+ * @title: Core repository-independent functions
+ * @short_description: Create, validate, and convert core data types
  *
- * Given a metadata object, return the signature of its #GVariant.
+ * These functions make up the core data manipulation functions of
+ * OSTree, such as serializing/deserializing metadata, converting
+ * between different types of checksums, and validating input.
  */
+
 const GVariantType *
 ostree_metadata_variant_type (OstreeObjectType objtype)
 {
@@ -690,6 +694,20 @@ ostree_content_stream_parse (gboolean                compressed,
   return ret;
 }
 
+/**
+ * ostree_content_file_parse:
+ * @compressed: Whether or not the stream is zlib-compressed
+ * @content_path: Path to file containing content
+ * @trusted: If %TRUE, assume the content has been validated
+ * @out_input: (out): The raw file content stream
+ * @out_file_info: (out): Normal metadata 
+ * @out_xattrs: (out): Extended attributes
+ * @cancellable:
+ * @error:
+ *
+ * A thin wrapper for ostree_content_stream_parse(); this function
+ * converts an object content stream back into components.
+ */
 gboolean
 ostree_content_file_parse (gboolean                compressed,
                            GFile                  *content_path,
@@ -922,6 +940,13 @@ ostree_checksum_file_async_finish (GFile          *f,
   return TRUE;
 }
 
+/**
+ * ostree_create_directory_metadata:
+ * @dir_info: a #GFileInfo containing directory information
+ * @xattrs: (allow-none): Optional extended attributes
+ *
+ * Returns: (transfer full): A new #GVariant containing %OSTREE_OBJECT_TYPE_DIR_META
+ */
 GVariant *
 ostree_create_directory_metadata (GFileInfo    *dir_info,
                                   GVariant     *xattrs)
@@ -938,6 +963,17 @@ ostree_create_directory_metadata (GFileInfo    *dir_info,
   return ret_metadata;
 }
 
+/**
+ * ostree_set_xattrs:
+ * @f: a file
+ * @xattrs: Extended attribute list
+ * @cancellable:
+ * @error:
+ *
+ * For each attribute in @xattrs, replace the value (if any) of @f for
+ * that attribute.  This function does not clear other existing
+ * attributes.
+ */
 gboolean
 ostree_set_xattrs (GFile  *f, 
                    GVariant *xattrs, 
@@ -978,6 +1014,12 @@ ostree_set_xattrs (GFile  *f,
   return ret;
 }
 
+/**
+ * ostree_object_type_to_string:
+ * @objtype: an #OstreeObjectType
+ *
+ * Serialize @objtype to a string; this is used for file extensions.
+ */
 const char *
 ostree_object_type_to_string (OstreeObjectType objtype)
 {
@@ -997,6 +1039,12 @@ ostree_object_type_to_string (OstreeObjectType objtype)
     }
 }
 
+/**
+ * ostree_object_type_from_string:
+ * @str: A stringified version of #OstreeObjectType
+ *
+ * The reverse of ostree_object_type_to_string().
+ */
 OstreeObjectType
 ostree_object_type_from_string (const char *str)
 {
@@ -1012,6 +1060,13 @@ ostree_object_type_from_string (const char *str)
   return 0;
 }
 
+/**
+ * ostree_object_to_string:
+ * @checksum: An ASCII checksum
+ * @objtype: Object type
+ *
+ * Returns: A string containing both @checksum and a stringifed version of @objtype
+ */
 char *
 ostree_object_to_string (const char *checksum,
                          OstreeObjectType objtype)
@@ -1019,6 +1074,14 @@ ostree_object_to_string (const char *checksum,
   return g_strconcat (checksum, ".", ostree_object_type_to_string (objtype), NULL);
 }
 
+/**
+ * ostree_object_from_string:
+ * @str: An ASCII checksum
+ * @out_checksum: (out) (transfer full): Parsed checksum
+ * @out_objtype: (out): Parsed object type
+ *
+ * Reverse ostree_object_to_string().
+ */
 void
 ostree_object_from_string (const char *str,
                            gchar     **out_checksum,
@@ -1032,6 +1095,12 @@ ostree_object_from_string (const char *str,
   *out_objtype = ostree_object_type_from_string (dot + 1);
 }
 
+/**
+ * ostree_hash_object_name:
+ * @a: A #GVariant containing a serialized object
+ *
+ * Use this function with #GHashTable and ostree_object_name_serialize().
+ */
 guint
 ostree_hash_object_name (gconstpointer a)
 {
@@ -1045,6 +1114,13 @@ ostree_hash_object_name (gconstpointer a)
   return g_str_hash (checksum) + g_int_hash (&objtype_int);
 }
 
+/**
+ * ostree_cmp_checksum_bytes:
+ * @a: A binary checksum
+ * @b: A binary checksum
+ *
+ * Compare two binary checksums, using memcmp().
+ */
 int
 ostree_cmp_checksum_bytes (const guchar *a,
                            const guchar *b)
@@ -1052,6 +1128,13 @@ ostree_cmp_checksum_bytes (const guchar *a,
   return memcmp (a, b, 32);
 }
 
+/**
+ * ostree_object_name_serialize:
+ * @checksum: An ASCII checksum
+ * @objtype: An object type
+ *
+ * Returns: (transfer floating): A new floating #GVariant containing checksum string and objtype
+ */
 GVariant *
 ostree_object_name_serialize (const char *checksum,
                               OstreeObjectType objtype)
@@ -1061,6 +1144,15 @@ ostree_object_name_serialize (const char *checksum,
   return g_variant_new ("(su)", checksum, (guint32)objtype);
 }
 
+/**
+ * ostree_object_name_deserialize:
+ * @variant: A #GVariant of type (su)
+ * @out_checksum: (out) (transfer none): Pointer into string memory of @variant with checksum
+ * @out_objtype: (out): Return object type
+ *
+ * Reverse ostree_object_name_serialize().  Note that @out_checksum is
+ * only valid for the lifetime of @variant, and must not be freed.
+ */
 void
 ostree_object_name_deserialize (GVariant         *variant,
                                 const char      **out_checksum,
@@ -1103,6 +1195,12 @@ ostree_checksum_inplace_to_bytes (const char *checksum,
     }
 }
 
+/**
+ * ostree_checksum_to_bytes:
+ * @checksum: An ASCII checksum
+ *
+ * Returns: (transfer full) (array fixed-size=32): Binary checksum from @checksum of length 32; free with g_free().
+ */
 guchar *
 ostree_checksum_to_bytes (const char *checksum)
 {
@@ -1111,6 +1209,12 @@ ostree_checksum_to_bytes (const char *checksum)
   return ret;
 }
 
+/**
+ * ostree_checksum_to_bytes_v:
+ * @checksum: An ASCII checksum
+ *
+ * Returns: (transfer full): New #GVariant of type ay with length 32
+ */
 GVariant *
 ostree_checksum_to_bytes_v (const char *checksum)
 {
@@ -1119,6 +1223,13 @@ ostree_checksum_to_bytes_v (const char *checksum)
   return ot_gvariant_new_bytearray ((guchar*)result, 32);
 }
 
+/**
+ * ostree_checksum_inplace_from_bytes: (skip)
+ * @csum: (array fixed-size=32): An binary checksum of length 32
+ * @buf: Output location, must be at least 65 bytes in length
+ *
+ * Overwrite the contents of @buf with stringified version of @csum.
+ */
 void
 ostree_checksum_inplace_from_bytes (const guchar *csum,
                                     char         *buf)
@@ -1135,6 +1246,12 @@ ostree_checksum_inplace_from_bytes (const guchar *csum,
   buf[j] = '\0';
 }
 
+/**
+ * ostree_checksum_from_bytes:
+ * @csum: (array fixed-size=32): An binary checksum of length 32
+ *
+ * Returns: (transfer full): String form of @csum
+ */
 char *
 ostree_checksum_from_bytes (const guchar *csum)
 {
@@ -1143,12 +1260,24 @@ ostree_checksum_from_bytes (const guchar *csum)
   return ret;
 }
 
+/**
+ * ostree_checksum_from_bytes_v:
+ * @csum_v: #GVariant of type ay
+ *
+ * Returns: (transfer full): String form of @csum_bytes
+ */
 char *
-ostree_checksum_from_bytes_v (GVariant *csum_bytes)
+ostree_checksum_from_bytes_v (GVariant *csum_v)
 {
-  return ostree_checksum_from_bytes (ostree_checksum_bytes_peek (csum_bytes));
+  return ostree_checksum_from_bytes (ostree_checksum_bytes_peek (csum_v));
 }
 
+/**
+ * ostree_checksum_bytes_peek:
+ * @bytes: #GVariant of type ay
+ *
+ * Returns: (transfer none): Binary checksum data in @bytes; do not free
+ */
 const guchar *
 ostree_checksum_bytes_peek (GVariant *bytes)
 {
@@ -1156,6 +1285,14 @@ ostree_checksum_bytes_peek (GVariant *bytes)
   return g_variant_get_fixed_array (bytes, &n_elts, 1);
 }
 
+/**
+ * ostree_get_relative_object_path:
+ * @checksum: ASCII checksum string
+ * @type: Object type
+ * @compressed: Whether or not the repository object is compressed
+ *
+ * Returns: (transfer full): Relative path for a loose object
+ */
 char *
 ostree_get_relative_object_path (const char         *checksum,
                                  OstreeObjectType    type,

src/libostree/ostree-core.h

@@ -126,10 +126,10 @@ gboolean ostree_validate_checksum_string (const char *sha256,
 guchar *ostree_checksum_to_bytes (const char *checksum);
 GVariant *ostree_checksum_to_bytes_v (const char *checksum);
 
-char * ostree_checksum_from_bytes (const guchar *bytes);
+char * ostree_checksum_from_bytes (const guchar *csum);
-char * ostree_checksum_from_bytes_v (GVariant *bytes);
+char * ostree_checksum_from_bytes_v (GVariant *csum_v);
 
-void ostree_checksum_inplace_from_bytes (const guchar *bytes,
+void ostree_checksum_inplace_from_bytes (const guchar *csum,
                                          char         *buf);
 
 void ostree_checksum_inplace_to_bytes (const char *checksum,
@@ -230,7 +230,7 @@ gboolean ostree_content_file_parse (gboolean                compressed,
                                     GError                **error);
 
 gboolean ostree_write_file_header_update_checksum (GOutputStream         *out,
-                                                   GVariant              *header,
+                                                   GVariant              *variant,
                                                    GChecksum             *checksum,
                                                    GCancellable          *cancellable,
                                                    GError               **error);