Set up gtkdoc for razor.
Despite its name, gtkdoc doesn't require gtk+ and is a nice way to
generate DocBook format API documentation.
1.1 --- a/autogen.sh Mon Jun 23 10:31:04 2008 -0400
1.2 +++ b/autogen.sh Mon Jun 23 13:54:56 2008 -0400
1.3 @@ -84,6 +84,8 @@
1.4
1.5 intltoolize --copy --force --automake || exit 1
1.6
1.7 +gtkdocize --copy --flavour no-tmpl
1.8 +
1.9 conf_flags="--enable-maintainer-mode"
1.10
1.11 if test x$NOCONFIGURE = x; then
2.1 --- a/configure.ac Mon Jun 23 10:31:04 2008 -0400
2.2 +++ b/configure.ac Mon Jun 23 13:54:56 2008 -0400
2.3 @@ -168,6 +168,8 @@
2.4 AM_GLIB_GNU_GETTEXT
2.5 AC_DEFINE_UNQUOTED([GETTEXT_PACKAGE],["$GETTEXT_PACKAGE"],[gettext domain])
2.6
2.7 +GTK_DOC_CHECK([1.9])
2.8 +
2.9 AC_OUTPUT([
2.10 Makefile
2.11 data/razor.pc
2.12 @@ -175,6 +177,7 @@
2.13 librazor/Makefile
2.14 src/Makefile
2.15 docs/Makefile
2.16 +docs/version.xml
2.17 po/Makefile.in
2.18 ])
2.19
3.1 --- a/docs/Makefile.am Mon Jun 23 10:31:04 2008 -0400
3.2 +++ b/docs/Makefile.am Mon Jun 23 13:54:56 2008 -0400
3.3 @@ -1,3 +1,33 @@
3.4 +# The name of the module.
3.5 +DOC_MODULE=razor
3.6 +
3.7 +# The top-level SGML file.
3.8 +DOC_MAIN_SGML_FILE=razor-docs.xml
3.9 +
3.10 +# Extra options to supply to gtkdoc-scan
3.11 +IGNORE_HFILES = config.h razor-internal.h
3.12 +
3.13 +# The directory containing the source code. Relative to $(srcdir)
3.14 +DOC_SOURCE_DIR=$(top_srcdir)/librazor
3.15 +
3.16 +# Used for dependencies
3.17 +HFILE_GLOB=$(top_srcdir)/librazor/*.h
3.18 +CFILE_GLOB=$(top_srcdir)/librazor/*.c
3.19 +
3.20 +# Extra options to supply to gtkdoc-mkdb
3.21 +MKDB_OPTIONS=--sgml-mode --output-format=xml
3.22 +
3.23 +# Extra options to supply to gtkdoc-mktmpl
3.24 +MKTMPL_OPTIONS=
3.25 +
3.26 +if ENABLE_GTK_DOC
3.27 +include $(top_srcdir)/gtk-doc.make
3.28 +else
3.29 +EXTRA_DIST =
3.30 +endif
3.31 +
3.32 +# Version information for marking the documentation
3.33 +EXTRA_DIST += version.xml.in
3.34
3.35 docsdir = $(datadir)/doc/razor
3.36 dist_docs_DATA = \
4.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
4.2 +++ b/docs/razor-docs.xml Mon Jun 23 13:54:56 2008 -0400
4.3 @@ -0,0 +1,85 @@
4.4 +<?xml version="1.0"?>
4.5 +<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
4.6 + "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd" [
4.7 +<!ENTITY version SYSTEM "version.xml">
4.8 +]>
4.9 +<book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
4.10 + <bookinfo>
4.11 + <title>Razor Library Reference Manual</title>
4.12 + <releaseinfo>Version &version;</releaseinfo>
4.13 + <authorgroup>
4.14 + <author>
4.15 + <firstname>Kristian</firstname>
4.16 + <surname>Høgsberg</surname>
4.17 + <affiliation>
4.18 + <address>
4.19 + <email>krh@redhat.com</email>
4.20 + </address>
4.21 + </affiliation>
4.22 + </author>
4.23 + </authorgroup>
4.24 +
4.25 + <copyright>
4.26 + <year>2008</year>
4.27 + <holder>Razor Authors</holder>
4.28 + </copyright>
4.29 +
4.30 + <copyright>
4.31 + <year>2008</year>
4.32 + <holder>Red Hat, Inc</holder>
4.33 + </copyright>
4.34 +
4.35 + <legalnotice>
4.36 + <para>
4.37 + Permission is granted to copy, distribute and/or modify this
4.38 + document under the terms of the <citetitle>GNU Free
4.39 + Documentation License</citetitle>, Version 1.1 or any later
4.40 + version published by the Free Software Foundation with no
4.41 + Invariant Sections, no Front-Cover Texts, and no Back-Cover
4.42 + Texts. You may obtain a copy of the <citetitle>GNU Free
4.43 + Documentation License</citetitle> from the Free Software
4.44 + Foundation by visiting <ulink type="http"
4.45 + url="http://www.fsf.org">their Web site</ulink> or by writing
4.46 + to:
4.47 +
4.48 + <address>
4.49 + The Free Software Foundation, Inc.,
4.50 + <street>59 Temple Place</street> - Suite 330,
4.51 + <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>,
4.52 + <country>USA</country>
4.53 + </address>
4.54 + </para>
4.55 + </legalnotice>
4.56 + </bookinfo>
4.57 +
4.58 + <reference id="ref-design">
4.59 + <title>Design Overview</title>
4.60 + <partintro>
4.61 + <para>
4.62 + This part presents the design documentation for razor.
4.63 + </para>
4.64 + </partintro>
4.65 + </reference>
4.66 +
4.67 + <reference id="ref-core">
4.68 + <title>Core API Reference</title>
4.69 + <partintro>
4.70 + <para>
4.71 + This part presents the class and function reference for the
4.72 + core razor library.
4.73 + </para>
4.74 + </partintro>
4.75 + <xi:include href="xml/set.xml"/>
4.76 + <xi:include href="xml/importer.xml"/>
4.77 + <xi:include href="xml/iterator.xml"/>
4.78 + <xi:include href="xml/transaction.xml"/>
4.79 + <xi:include href="xml/rpm.xml"/>
4.80 + <xi:include href="xml/root.xml"/>
4.81 + <xi:include href="xml/misc.xml"/>
4.82 + </reference>
4.83 +
4.84 + <index>
4.85 + <title>Index</title>
4.86 + </index>
4.87 +
4.88 +</book>
5.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
5.2 +++ b/docs/razor-sections.txt Mon Jun 23 13:54:56 2008 -0400
5.3 @@ -0,0 +1,100 @@
5.4 +<SECTION>
5.5 +<FILE>set</FILE>
5.6 +razor_set
5.7 +razor_set_create
5.8 +razor_set_open
5.9 +razor_set_destroy
5.10 +razor_set_write_to_fd
5.11 +razor_set_write
5.12 +razor_set_open_details
5.13 +razor_set_open_files
5.14 +razor_set_get_package
5.15 +razor_set_list_files
5.16 +razor_set_list_package_files
5.17 +razor_set_list_unsatisfied
5.18 +razor_set_create_from_yum
5.19 +razor_set_create_from_rpmdb
5.20 +razor_diff_callback_t
5.21 +razor_set_diff
5.22 +razor_set_create_remove_iterator
5.23 +razor_set_create_install_iterator
5.24 +</SECTION>
5.25 +
5.26 +<SECTION>
5.27 +<FILE>transaction</FILE>
5.28 +razor_transaction_create
5.29 +razor_transaction_install_package
5.30 +razor_transaction_remove_package
5.31 +razor_transaction_update_package
5.32 +razor_transaction_update_all
5.33 +razor_transaction_resolve
5.34 +razor_transaction_describe
5.35 +razor_transaction_finish
5.36 +razor_transaction_destroy
5.37 +razor_transaction_unsatisfied_property
5.38 +</SECTION>
5.39 +
5.40 +<SECTION>
5.41 +<FILE>importer</FILE>
5.42 +razor_importer
5.43 +razor_importer_create
5.44 +razor_importer_destroy
5.45 +razor_importer_begin_package
5.46 +razor_importer_add_details
5.47 +razor_importer_add_property
5.48 +razor_importer_add_file
5.49 +razor_importer_finish_package
5.50 +razor_importer_add_rpm
5.51 +razor_importer_finish
5.52 +</SECTION>
5.53 +
5.54 +<SECTION>
5.55 +<FILE>rpm</FILE>
5.56 +razor_rpm
5.57 +razor_rpm_open
5.58 +razor_rpm_install
5.59 +razor_rpm_close
5.60 +</SECTION>
5.61 +
5.62 +<SECTION>
5.63 +<FILE>root</FILE>
5.64 +razor_root
5.65 +razor_root_create
5.66 +razor_root_open
5.67 +razor_root_open_read_only
5.68 +razor_root_get_system_set
5.69 +razor_root_close
5.70 +razor_root_update
5.71 +razor_root_commit
5.72 +</SECTION>
5.73 +
5.74 +<SECTION>
5.75 +<FILE>iterator</FILE>
5.76 +razor_package_iterator
5.77 +razor_package_iterator_create
5.78 +razor_package_iterator_create_for_property
5.79 +razor_package_iterator_create_for_file
5.80 +razor_package_iterator_next
5.81 +razor_package_iterator_destroy
5.82 +razor_package_query_create
5.83 +razor_package_query_add_package
5.84 +razor_package_query_add_iterator
5.85 +razor_package_query_finish
5.86 +razor_property_iterator
5.87 +razor_property_iterator_create
5.88 +razor_property_iterator_next
5.89 +razor_property_iterator_destroy
5.90 +</SECTION>
5.91 +
5.92 +<SECTION>
5.93 +<FILE>misc</FILE>
5.94 +razor_package
5.95 +razor_package_get_details
5.96 +
5.97 +razor_property
5.98 +razor_property_relation_to_string
5.99 +razor_property_type_to_string
5.100 +
5.101 +razor_build_evr
5.102 +razor_versioncmp
5.103 +</SECTION>
6.1 --- /dev/null Thu Jan 01 00:00:00 1970 +0000
6.2 +++ b/docs/version.xml.in Mon Jun 23 13:54:56 2008 -0400
6.3 @@ -0,0 +1,1 @@
6.4 +@VERSION@
7.1 --- a/librazor/razor.c Mon Jun 23 10:31:04 2008 -0400
7.2 +++ b/librazor/razor.c Mon Jun 23 13:54:56 2008 -0400
7.3 @@ -64,6 +64,7 @@
7.4 struct razor_set_section razor_details_sections[] = {
7.5 { RAZOR_DETAILS_STRING_POOL, offsetof(struct razor_set, details_string_pool) },
7.6 };
7.7 +
7.8 struct razor_set *
7.9 razor_set_create(void)
7.10 {
8.1 --- a/librazor/razor.h Mon Jun 23 10:31:04 2008 -0400
8.2 +++ b/librazor/razor.h Mon Jun 23 13:54:56 2008 -0400
8.3 @@ -22,10 +22,6 @@
8.4
8.5 #define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0]))
8.6
8.7 -struct razor_set;
8.8 -struct razor_package;
8.9 -struct razor_property;
8.10 -
8.11 enum razor_repo_file_type {
8.12 RAZOR_REPO_FILE_MAIN,
8.13 RAZOR_REPO_FILE_DETAILS,
8.14 @@ -53,11 +49,26 @@
8.15 RAZOR_PROPERTY_POSTUN = 1 << 8
8.16 };
8.17
8.18 -const char *
8.19 -razor_property_relation_to_string(struct razor_property *p);
8.20 -const char *
8.21 -razor_property_type_to_string(struct razor_property *p);
8.22 +/**
8.23 + * SECTION:set
8.24 + * @title: Package Set
8.25 + * @short_description: Represents a set of packages and their metadata.
8.26 + *
8.27 + * This object represents a set of packages, their dependency
8.28 + * information, the file lists and a number of other details.
8.29 + **/
8.30
8.31 +struct razor_set;
8.32 +struct razor_package;
8.33 +struct razor_property;
8.34 +
8.35 +/**
8.36 + * razor_set_create:
8.37 + *
8.38 + * Create a new #razor_set object.
8.39 + *
8.40 + * Returns: the new #razor_set object.
8.41 + **/
8.42 struct razor_set *razor_set_create(void);
8.43 struct razor_set *razor_set_open(const char *filename);
8.44 void razor_set_destroy(struct razor_set *set);
8.45 @@ -77,9 +88,37 @@
8.46 const char **summary, const char **description,
8.47 const char **url, const char **license);
8.48
8.49 +
8.50 +/**
8.51 + * SECTION:iterator
8.52 + * @title: Iterators
8.53 + * @short_description: Objects for traversing packages or properties.
8.54 + *
8.55 + * The razor iterator objects provides a way to iterate through a set
8.56 + * of packages or properties.
8.57 + **/
8.58 +
8.59 struct razor_package_iterator;
8.60 +
8.61 +/**
8.62 + * razor_package_iterator_create:
8.63 + *
8.64 + * Create a new #razor_package_iterator object.
8.65 + *
8.66 + * Returns: the new #razor_package_iterator object.
8.67 + **/
8.68 +
8.69 struct razor_package_iterator *
8.70 razor_package_iterator_create(struct razor_set *set);
8.71 +
8.72 +/**
8.73 + * razor_package_iterator_create_for_property:
8.74 + *
8.75 + * Create a new #razor_package_iterator object for the packages that
8.76 + * own the given property.
8.77 + *
8.78 + * Returns: the new #razor_package_iterator object.
8.79 + **/
8.80 struct razor_package_iterator *
8.81 razor_package_iterator_create_for_property(struct razor_set *set,
8.82 struct razor_property *property);
8.83 @@ -144,7 +183,14 @@
8.84 razor_set_create_install_iterator(struct razor_set *set,
8.85 struct razor_set *next);
8.86
8.87 -/* Package transactions */
8.88 +/**
8.89 + * SECTION:transaction
8.90 + * @title: Transaction
8.91 + * @short_description: Create a new package set by merging two or more sets.
8.92 + *
8.93 + * The razor transaction object provides a way to create a new package set
8.94 + * from packages from one or more other package sets.
8.95 + **/
8.96
8.97 struct razor_transaction *
8.98 razor_transaction_create(struct razor_set *system, struct razor_set *upstream);
8.99 @@ -166,11 +212,30 @@
8.100 uint32_t flags,
8.101 const char *version);
8.102
8.103 -/* Importer interface; for building a razor set from external sources,
8.104 - * like yum, rpmdb or razor package files. */
8.105 +/**
8.106 + * SECTION:rpm
8.107 + * @title: Razor RPM
8.108 + * @short_description: Operating on RPM files.
8.109 + *
8.110 + * Functions for open RPM files and extracting information and
8.111 + * installing or removing RPM files.
8.112 + **/
8.113
8.114 +struct razor_rpm;
8.115 +
8.116 +struct razor_rpm *razor_rpm_open(const char *filename);
8.117 +int razor_rpm_install(struct razor_rpm *rpm, const char *root);
8.118 +int razor_rpm_close(struct razor_rpm *rpm);
8.119 +
8.120 +/**
8.121 + * SECTION:importer
8.122 + * @title: Importer
8.123 + * @short_description: A mechanism for building #razor_set objects
8.124 + *
8.125 + * For building a razor set from external sources, like yum, rpmdb or
8.126 + * RPM files.
8.127 + **/
8.128 struct razor_importer;
8.129 -struct razor_rpm;
8.130
8.131 struct razor_importer *razor_importer_create(void);
8.132 void razor_importer_destroy(struct razor_importer *importer);
8.133 @@ -196,23 +261,17 @@
8.134
8.135 struct razor_set *razor_importer_finish(struct razor_importer *importer);
8.136
8.137 -void razor_build_evr(char *evr_buf, int size, const char *epoch,
8.138 - const char *version, const char *release);
8.139 -int razor_versioncmp(const char *s1, const char *s2);
8.140 -
8.141 struct razor_set *razor_set_create_from_yum(void);
8.142 struct razor_set *razor_set_create_from_rpmdb(void);
8.143
8.144 -/* RPM functions */
8.145 -
8.146 -struct razor_rpm *razor_rpm_open(const char *filename);
8.147 -int razor_rpm_install(struct razor_rpm *rpm, const char *root);
8.148 -int razor_rpm_close(struct razor_rpm *rpm);
8.149 -
8.150 -
8.151 -/* Razor root functions. The root data structure encapsulates
8.152 - * filesystem conventions and the locking protocol. */
8.153 -
8.154 +/**
8.155 + * SECTION:root
8.156 + * @title: Root
8.157 + * @short_description: Functions for accessing an install root.
8.158 + *
8.159 + * The #razor_root object encapsulate access to and locking of a razor
8.160 + * install root.
8.161 + **/
8.162 struct razor_root;
8.163
8.164 int razor_root_create(const char *root);
8.165 @@ -223,4 +282,23 @@
8.166 void razor_root_update(struct razor_root *root, struct razor_set *next);
8.167 int razor_root_commit(struct razor_root *root);
8.168
8.169 +
8.170 +/**
8.171 + * SECTION:misc
8.172 + * @title: Miscellaneous Functions
8.173 + * @short_description: Various helper functions
8.174 + *
8.175 + * Functions that doesn't fit anywhere else.
8.176 + **/
8.177 +
8.178 +const char *
8.179 +razor_property_relation_to_string(struct razor_property *p);
8.180 +const char *
8.181 +razor_property_type_to_string(struct razor_property *p);
8.182 +
8.183 +void razor_build_evr(char *evr_buf, int size, const char *epoch,
8.184 + const char *version, const char *release);
8.185 +int razor_versioncmp(const char *s1, const char *s2);
8.186 +
8.187 +
8.188 #endif /* _RAZOR_H_ */