Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
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
View
2  autogen.sh
@@ -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
View
3  configure.ac
@@ -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
])
View
30 docs/Makefile.am
@@ -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 = \
View
85 docs/razor-docs.xml
@@ -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>
View
100 docs/razor-sections.txt
@@ -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>
View
1  docs/version.xml.in
@@ -0,0 +1 @@
+@VERSION@
View
1  librazor/razor.c
@@ -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)
{
View
130 librazor/razor.h
@@ -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.