Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Set up gtkdoc for razor.

Despite its name, gtkdoc doesn't require gtk+ and is a nice way to
generate DocBook format API documentation.
  • Loading branch information...
commit 13de66077f3f4c67705589bf0c36c25d9b9e10e1 1 parent ef514b2
Kristian Høgsberg authored
2  autogen.sh
View
@@ -84,6 +84,8 @@ esac
intltoolize --copy --force --automake || exit 1
+gtkdocize --copy --flavour no-tmpl
+
conf_flags="--enable-maintainer-mode"
if test x$NOCONFIGURE = x; then
3  configure.ac
View
@@ -168,6 +168,8 @@ AC_SUBST([GETTEXT_PACKAGE])
AM_GLIB_GNU_GETTEXT
AC_DEFINE_UNQUOTED([GETTEXT_PACKAGE],["$GETTEXT_PACKAGE"],[gettext domain])
+GTK_DOC_CHECK([1.9])
+
AC_OUTPUT([
Makefile
data/razor.pc
@@ -175,6 +177,7 @@ data/Makefile
librazor/Makefile
src/Makefile
docs/Makefile
+docs/version.xml
po/Makefile.in
])
30 docs/Makefile.am
View
@@ -1,3 +1,33 @@
+# The name of the module.
+DOC_MODULE=razor
+
+# The top-level SGML file.
+DOC_MAIN_SGML_FILE=razor-docs.xml
+
+# Extra options to supply to gtkdoc-scan
+IGNORE_HFILES = config.h razor-internal.h
+
+# The directory containing the source code. Relative to $(srcdir)
+DOC_SOURCE_DIR=$(top_srcdir)/librazor
+
+# Used for dependencies
+HFILE_GLOB=$(top_srcdir)/librazor/*.h
+CFILE_GLOB=$(top_srcdir)/librazor/*.c
+
+# Extra options to supply to gtkdoc-mkdb
+MKDB_OPTIONS=--sgml-mode --output-format=xml
+
+# Extra options to supply to gtkdoc-mktmpl
+MKTMPL_OPTIONS=
+
+if ENABLE_GTK_DOC
+include $(top_srcdir)/gtk-doc.make
+else
+EXTRA_DIST =
+endif
+
+# Version information for marking the documentation
+EXTRA_DIST += version.xml.in
docsdir = $(datadir)/doc/razor
dist_docs_DATA = \
85 docs/razor-docs.xml
View
@@ -0,0 +1,85 @@
+<?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>Razor Library Reference Manual</title>
+ <releaseinfo>Version &version;</releaseinfo>
+ <authorgroup>
+ <author>
+ <firstname>Kristian</firstname>
+ <surname>Høgsberg</surname>
+ <affiliation>
+ <address>
+ <email>krh@redhat.com</email>
+ </address>
+ </affiliation>
+ </author>
+ </authorgroup>
+
+ <copyright>
+ <year>2008</year>
+ <holder>Razor Authors</holder>
+ </copyright>
+
+ <copyright>
+ <year>2008</year>
+ <holder>Red Hat, Inc</holder>
+ </copyright>
+
+ <legalnotice>
+ <para>
+ Permission is granted to copy, distribute and/or modify this
+ document under the terms of the <citetitle>GNU Free
+ Documentation License</citetitle>, Version 1.1 or any later
+ version published by the Free Software Foundation with no
+ Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. You may obtain a copy of the <citetitle>GNU Free
+ Documentation License</citetitle> from the Free Software
+ Foundation by visiting <ulink type="http"
+ url="http://www.fsf.org">their Web site</ulink> or by writing
+ to:
+
+ <address>
+ The Free Software Foundation, Inc.,
+ <street>59 Temple Place</street> - Suite 330,
+ <city>Boston</city>, <state>MA</state> <postcode>02111-1307</postcode>,
+ <country>USA</country>
+ </address>
+ </para>
+ </legalnotice>
+ </bookinfo>
+
+ <reference id="ref-design">
+ <title>Design Overview</title>
+ <partintro>
+ <para>
+ This part presents the design documentation for razor.
+ </para>
+ </partintro>
+ </reference>
+
+ <reference id="ref-core">
+ <title>Core API Reference</title>
+ <partintro>
+ <para>
+ This part presents the class and function reference for the
+ core razor library.
+ </para>
+ </partintro>
+ <xi:include href="xml/set.xml"/>
+ <xi:include href="xml/importer.xml"/>
+ <xi:include href="xml/iterator.xml"/>
+ <xi:include href="xml/transaction.xml"/>
+ <xi:include href="xml/rpm.xml"/>
+ <xi:include href="xml/root.xml"/>
+ <xi:include href="xml/misc.xml"/>
+ </reference>
+
+ <index>
+ <title>Index</title>
+ </index>
+
+</book>
100 docs/razor-sections.txt
View
@@ -0,0 +1,100 @@
+<SECTION>
+<FILE>set</FILE>
+razor_set
+razor_set_create
+razor_set_open
+razor_set_destroy
+razor_set_write_to_fd
+razor_set_write
+razor_set_open_details
+razor_set_open_files
+razor_set_get_package
+razor_set_list_files
+razor_set_list_package_files
+razor_set_list_unsatisfied
+razor_set_create_from_yum
+razor_set_create_from_rpmdb
+razor_diff_callback_t
+razor_set_diff
+razor_set_create_remove_iterator
+razor_set_create_install_iterator
+</SECTION>
+
+<SECTION>
+<FILE>transaction</FILE>
+razor_transaction_create
+razor_transaction_install_package
+razor_transaction_remove_package
+razor_transaction_update_package
+razor_transaction_update_all
+razor_transaction_resolve
+razor_transaction_describe
+razor_transaction_finish
+razor_transaction_destroy
+razor_transaction_unsatisfied_property
+</SECTION>
+
+<SECTION>
+<FILE>importer</FILE>
+razor_importer
+razor_importer_create
+razor_importer_destroy
+razor_importer_begin_package
+razor_importer_add_details
+razor_importer_add_property
+razor_importer_add_file
+razor_importer_finish_package
+razor_importer_add_rpm
+razor_importer_finish
+</SECTION>
+
+<SECTION>
+<FILE>rpm</FILE>
+razor_rpm
+razor_rpm_open
+razor_rpm_install
+razor_rpm_close
+</SECTION>
+
+<SECTION>
+<FILE>root</FILE>
+razor_root
+razor_root_create
+razor_root_open
+razor_root_open_read_only
+razor_root_get_system_set
+razor_root_close
+razor_root_update
+razor_root_commit
+</SECTION>
+
+<SECTION>
+<FILE>iterator</FILE>
+razor_package_iterator
+razor_package_iterator_create
+razor_package_iterator_create_for_property
+razor_package_iterator_create_for_file
+razor_package_iterator_next
+razor_package_iterator_destroy
+razor_package_query_create
+razor_package_query_add_package
+razor_package_query_add_iterator
+razor_package_query_finish
+razor_property_iterator
+razor_property_iterator_create
+razor_property_iterator_next
+razor_property_iterator_destroy
+</SECTION>
+
+<SECTION>
+<FILE>misc</FILE>
+razor_package
+razor_package_get_details
+
+razor_property
+razor_property_relation_to_string
+razor_property_type_to_string
+
+razor_build_evr
+razor_versioncmp
+</SECTION>
1  docs/version.xml.in
View
@@ -0,0 +1 @@
+@VERSION@
1  librazor/razor.c
View
@@ -64,6 +64,7 @@ struct razor_set_section razor_files_sections[] = {
struct razor_set_section razor_details_sections[] = {
{ RAZOR_DETAILS_STRING_POOL, offsetof(struct razor_set, details_string_pool) },
};
+
struct razor_set *
razor_set_create(void)
{
130 librazor/razor.h
View
@@ -22,10 +22,6 @@
#define ARRAY_SIZE(a) (sizeof(a) / sizeof((a)[0]))
-struct razor_set;
-struct razor_package;
-struct razor_property;
-
enum razor_repo_file_type {
RAZOR_REPO_FILE_MAIN,
RAZOR_REPO_FILE_DETAILS,
@@ -53,11 +49,26 @@ enum razor_property_flags {
RAZOR_PROPERTY_POSTUN = 1 << 8
};
-const char *
-razor_property_relation_to_string(struct razor_property *p);
-const char *
-razor_property_type_to_string(struct razor_property *p);
+/**
+ * SECTION:set
+ * @title: Package Set
+ * @short_description: Represents a set of packages and their metadata.
+ *
+ * This object represents a set of packages, their dependency
+ * information, the file lists and a number of other details.
+ **/
+struct razor_set;
+struct razor_package;
+struct razor_property;
+
+/**
+ * razor_set_create:
+ *
+ * Create a new #razor_set object.
+ *
+ * Returns: the new #razor_set object.
+ **/
struct razor_set *razor_set_create(void);
struct razor_set *razor_set_open(const char *filename);
void razor_set_destroy(struct razor_set *set);
@@ -77,9 +88,37 @@ razor_package_get_details(struct razor_set *set, struct razor_package *package,
const char **summary, const char **description,
const char **url, const char **license);
+
+/**
+ * SECTION:iterator
+ * @title: Iterators
+ * @short_description: Objects for traversing packages or properties.
+ *
+ * The razor iterator objects provides a way to iterate through a set
+ * of packages or properties.
+ **/
+
struct razor_package_iterator;
+
+/**
+ * razor_package_iterator_create:
+ *
+ * Create a new #razor_package_iterator object.
+ *
+ * Returns: the new #razor_package_iterator object.
+ **/
+
struct razor_package_iterator *
razor_package_iterator_create(struct razor_set *set);
+
+/**
+ * razor_package_iterator_create_for_property:
+ *
+ * Create a new #razor_package_iterator object for the packages that
+ * own the given property.
+ *
+ * Returns: the new #razor_package_iterator object.
+ **/
struct razor_package_iterator *
razor_package_iterator_create_for_property(struct razor_set *set,
struct razor_property *property);
@@ -144,7 +183,14 @@ struct razor_package_iterator *
razor_set_create_install_iterator(struct razor_set *set,
struct razor_set *next);
-/* Package transactions */
+/**
+ * SECTION:transaction
+ * @title: Transaction
+ * @short_description: Create a new package set by merging two or more sets.
+ *
+ * The razor transaction object provides a way to create a new package set
+ * from packages from one or more other package sets.
+ **/
struct razor_transaction *
razor_transaction_create(struct razor_set *system, struct razor_set *upstream);
@@ -166,12 +212,31 @@ int razor_transaction_unsatisfied_property(struct razor_transaction *trans,
uint32_t flags,
const char *version);
-/* Importer interface; for building a razor set from external sources,
- * like yum, rpmdb or razor package files. */
+/**
+ * SECTION:rpm
+ * @title: Razor RPM
+ * @short_description: Operating on RPM files.
+ *
+ * Functions for open RPM files and extracting information and
+ * installing or removing RPM files.
+ **/
-struct razor_importer;
struct razor_rpm;
+struct razor_rpm *razor_rpm_open(const char *filename);
+int razor_rpm_install(struct razor_rpm *rpm, const char *root);
+int razor_rpm_close(struct razor_rpm *rpm);
+
+/**
+ * SECTION:importer
+ * @title: Importer
+ * @short_description: A mechanism for building #razor_set objects
+ *
+ * For building a razor set from external sources, like yum, rpmdb or
+ * RPM files.
+ **/
+struct razor_importer;
+
struct razor_importer *razor_importer_create(void);
void razor_importer_destroy(struct razor_importer *importer);
void razor_importer_begin_package(struct razor_importer *importer,
@@ -196,23 +261,17 @@ int razor_importer_add_rpm(struct razor_importer *importer,
struct razor_set *razor_importer_finish(struct razor_importer *importer);
-void razor_build_evr(char *evr_buf, int size, const char *epoch,
- const char *version, const char *release);
-int razor_versioncmp(const char *s1, const char *s2);
-
struct razor_set *razor_set_create_from_yum(void);
struct razor_set *razor_set_create_from_rpmdb(void);
-/* RPM functions */
-
-struct razor_rpm *razor_rpm_open(const char *filename);
-int razor_rpm_install(struct razor_rpm *rpm, const char *root);
-int razor_rpm_close(struct razor_rpm *rpm);
-
-
-/* Razor root functions. The root data structure encapsulates
- * filesystem conventions and the locking protocol. */
-
+/**
+ * SECTION:root
+ * @title: Root
+ * @short_description: Functions for accessing an install root.
+ *
+ * The #razor_root object encapsulate access to and locking of a razor
+ * install root.
+ **/
struct razor_root;
int razor_root_create(const char *root);
@@ -223,4 +282,23 @@ int razor_root_close(struct razor_root *root);
void razor_root_update(struct razor_root *root, struct razor_set *next);
int razor_root_commit(struct razor_root *root);
+
+/**
+ * SECTION:misc
+ * @title: Miscellaneous Functions
+ * @short_description: Various helper functions
+ *
+ * Functions that doesn't fit anywhere else.
+ **/
+
+const char *
+razor_property_relation_to_string(struct razor_property *p);
+const char *
+razor_property_type_to_string(struct razor_property *p);
+
+void razor_build_evr(char *evr_buf, int size, const char *epoch,
+ const char *version, const char *release);
+int razor_versioncmp(const char *s1, const char *s2);
+
+
#endif /* _RAZOR_H_ */
Please sign in to comment.
Something went wrong with that request. Please try again.