From 13de66077f3f4c67705589bf0c36c25d9b9e10e1 Mon Sep 17 00:00:00 2001 From: =?utf8?q?Kristian=20H=C3=B8gsberg?= Date: Mon, 23 Jun 2008 13:48:18 -0400 Subject: [PATCH] Set up gtkdoc for razor. Despite its name, gtkdoc doesn't require gtk+ and is a nice way to generate DocBook format API documentation. --- autogen.sh | 2 + configure.ac | 3 + docs/Makefile.am | 30 +++++++++++ docs/razor-docs.xml | 85 ++++++++++++++++++++++++++++++ docs/razor-sections.txt | 100 ++++++++++++++++++++++++++++++++++++ docs/version.xml.in | 1 + librazor/razor.c | 1 + librazor/razor.h | 130 +++++++++++++++++++++++++++++++++++++--------- 8 files changed, 326 insertions(+), 26 deletions(-) create mode 100644 docs/razor-docs.xml create mode 100644 docs/razor-sections.txt create mode 100644 docs/version.xml.in diff --git a/autogen.sh b/autogen.sh index 347c3e1..a70e81e 100755 --- a/autogen.sh +++ b/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 diff --git a/configure.ac b/configure.ac index a6559d4..7a5a9a3 100644 --- a/configure.ac +++ b/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 ]) diff --git a/docs/Makefile.am b/docs/Makefile.am index f9c16c8..342e364 100644 --- a/docs/Makefile.am +++ b/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 = \ diff --git a/docs/razor-docs.xml b/docs/razor-docs.xml new file mode 100644 index 0000000..f2866a5 --- /dev/null +++ b/docs/razor-docs.xml @@ -0,0 +1,85 @@ + + +]> + + + Razor Library Reference Manual + Version &version; + + + Kristian + Høgsberg + +
+ krh@redhat.com +
+ + + + + + 2008 + Razor Authors + + + + 2008 + Red Hat, Inc + + + + + Permission is granted to copy, distribute and/or modify this + document under the terms of the GNU Free + Documentation License, 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 GNU Free + Documentation License from the Free Software + Foundation by visiting their Web site or by writing + to: + +
+ The Free Software Foundation, Inc., + 59 Temple Place - Suite 330, + Boston, MA 02111-1307, + USA +
+ + + + + + Design Overview + + + This part presents the design documentation for razor. + + + + + + Core API Reference + + + This part presents the class and function reference for the + core razor library. + + + + + + + + + + + + + Index + + + diff --git a/docs/razor-sections.txt b/docs/razor-sections.txt new file mode 100644 index 0000000..49c9fce --- /dev/null +++ b/docs/razor-sections.txt @@ -0,0 +1,100 @@ +
+set +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 +
+ +
+transaction +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 +
+ +
+importer +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 +
+ +
+rpm +razor_rpm +razor_rpm_open +razor_rpm_install +razor_rpm_close +
+ +
+root +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 +
+ +
+iterator +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 +
+ +
+misc +razor_package +razor_package_get_details + +razor_property +razor_property_relation_to_string +razor_property_type_to_string + +razor_build_evr +razor_versioncmp +
diff --git a/docs/version.xml.in b/docs/version.xml.in new file mode 100644 index 0000000..d78bda9 --- /dev/null +++ b/docs/version.xml.in @@ -0,0 +1 @@ +@VERSION@ diff --git a/librazor/razor.c b/librazor/razor.c index 53187a6..74f051e 100644 --- a/librazor/razor.c +++ b/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) { diff --git a/librazor/razor.h b/librazor/razor.h index 5040dc0..4216bc6 100644 --- a/librazor/razor.h +++ b/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_ */ -- 1.7.1