[glabels] Updated libglabels documentation.

From: Jim Evins <jimevins src gnome org>
To: commits-list gnome org
Cc:
Subject: [glabels] Updated libglabels documentation.
Date: Sat, 5 Jun 2010 03:56:00 +0000 (UTC)
commit 3c200d2279f57999de42fb211ed878de3a62ad5b
Author: Jim Evins <evins snaught com>
Date:   Fri Jun 4 23:55:09 2010 -0400

    Updated libglabels documentation.

 docs/libglabels/libglabels-3.0-sections.txt |   15 +++++
 docs/libglabels/tmpl/category.sgml          |    3 +
 docs/libglabels/tmpl/db.sgml                |   84 +++++++++++++++++++++++++++
 docs/libglabels/tmpl/paper.sgml             |    3 +
 docs/libglabels/tmpl/str.sgml               |   12 ++++
 docs/libglabels/tmpl/template.sgml          |   40 +++++++++++++
 docs/libglabels/tmpl/units.sgml             |    3 +
 docs/libglabels/tmpl/vendor.sgml            |    3 +
 docs/libglabels/tmpl/xml-category.sgml      |    3 +
 docs/libglabels/tmpl/xml-paper.sgml         |    3 +
 docs/libglabels/tmpl/xml-template.sgml      |    3 +
 docs/libglabels/tmpl/xml-vendor.sgml        |    3 +
 docs/libglabels/tmpl/xml.sgml               |    3 +
 libglabels/db.c                             |   36 +++++++++++
 libglabels/str.c                            |   12 +++-
 15 files changed, 223 insertions(+), 3 deletions(-)
---
diff --git a/docs/libglabels/libglabels-3.0-sections.txt b/docs/libglabels/libglabels-3.0-sections.txt
index 9391808..bdf482d 100644
--- a/docs/libglabels/libglabels-3.0-sections.txt
+++ b/docs/libglabels/libglabels-3.0-sections.txt
@@ -2,8 +2,13 @@
 <FILE>db</FILE>
 <INCLUDE>libglabels/db.h</INCLUDE>
 lglDbRegStatus
+lglDbDeleteStatus
 <SUBSECTION Init Functions>
 lgl_db_init
+<SUBSECTION Notification>
+lglDbNotifyFunc
+lgl_db_notify_add
+lgl_db_notify_remove
 <SUBSECTION Paper Functions>
 lgl_db_get_paper_id_list
 lgl_db_free_paper_id_list
@@ -30,10 +35,13 @@ lgl_db_get_brand_list
 lgl_db_free_brand_list
 <SUBSECTION Template Functions>
 lgl_db_register_template
+lgl_db_delete_template_by_brand_part
+lgl_db_delete_template_by_name
 lgl_db_does_template_exist
 lgl_db_does_template_name_exist
 lgl_db_get_template_name_list_unique
 lgl_db_get_template_name_list_all
+lgl_db_get_similar_template_name_list
 lgl_db_free_template_name_list
 lgl_db_lookup_template_from_name
 lgl_db_lookup_template_from_brand_part
@@ -46,6 +54,7 @@ lgl_db_lookup_vendor_from_name
 lgl_db_print_known_papers
 lgl_db_print_known_categories
 lgl_db_print_known_templates
+lgl_db_print_known_vendors
 lgl_db_print_aliases
 </SECTION>
 
@@ -89,6 +98,7 @@ lgl_template_do_templates_match
 lgl_template_does_brand_match
 lgl_template_does_page_size_match
 lgl_template_does_category_match
+lgl_template_are_templates_identical
 <SUBSECTION Alias Functions>
 lgl_template_alias_new
 lgl_template_alias_dup
@@ -106,6 +116,8 @@ lgl_template_frame_add_markup
 lgl_template_frame_get_size
 lgl_template_frame_get_n_labels
 lgl_template_frame_get_origins
+lgl_template_frame_get_layout_description
+lgl_template_frame_get_size_description
 <SUBSECTION Layout Functions>
 lgl_template_layout_new
 lgl_template_layout_dup
@@ -118,6 +130,8 @@ lgl_template_markup_rect_new
 lgl_template_markup_ellipse_new
 lgl_template_markup_dup
 lgl_template_markup_free
+<SUBSECTION Debugging Functions>
+lgl_template_print
 </SECTION>
 
 <SECTION>
@@ -225,5 +239,6 @@ lgl_units_get_units_per_point
 <INCLUDE>libglabels/str.h</INCLUDE>
 lgl_str_utf8_casecmp
 lgl_str_part_name_cmp
+lgl_str_format_fraction
 </SECTION>
 
diff --git a/docs/libglabels/tmpl/category.sgml b/docs/libglabels/tmpl/category.sgml
index 2143fd1..41a6142 100644
--- a/docs/libglabels/tmpl/category.sgml
+++ b/docs/libglabels/tmpl/category.sgml
@@ -18,6 +18,9 @@ functions.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### STRUCT lglCategory ##### -->
 <para>
 This structure defines a category.
diff --git a/docs/libglabels/tmpl/db.sgml b/docs/libglabels/tmpl/db.sgml
index 4c2705b..2a253bc 100644
--- a/docs/libglabels/tmpl/db.sgml
+++ b/docs/libglabels/tmpl/db.sgml
@@ -18,6 +18,9 @@ the LibGlabels template database.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### ENUM lglDbRegStatus ##### -->
 <para>
 This enumeration defines a set of possible return values for lgl_db_register_template().
@@ -28,11 +31,48 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 @LGL_DB_REG_BRAND_PART_EXISTS: Registration failed because template with same brand and part name/number already exists.
 @LGL_DB_REG_FILE_WRITE_ERROR: Registration failed because an error while writing to disk.
 
+<!-- ##### ENUM lglDbDeleteStatus ##### -->
+<para>
+This enumeration defines a set of possible return values for lgl_db_delete_template_by_name() or lgl_db_delete_template_by_brand_part().
+</para>
+
+ LGL_DB_DELETE_OK: Deletion successful.
+ LGL_DB_DELETE_DOES_NOT_EXIST: Deletion failed because template with given brand and part name/number does not exist.
+ LGL_DB_DELETE_NOT_USER_DEFINED: Deletion failed because given template is not a user defined template.
+ LGL_DB_DELETE_FILE_ERROR: Deletion failed because of an error while attempting to remove template from disk.
+
 <!-- ##### FUNCTION lgl_db_init ##### -->
 <para>
 
 </para>
 
+ void: 
+
+
+<!-- ##### USER_FUNCTION lglDbNotifyFunc ##### -->
+<para>
+Defines the type of notify callback function to be called when database changes.
+</para>
+
+ user_data: Pointer to user data that is passed to the notify function.
+
+
+<!-- ##### FUNCTION lgl_db_notify_add ##### -->
+<para>
+
+</para>
+
+ func: 
+ user_data: 
+ Returns: 
+
+
+<!-- ##### FUNCTION lgl_db_notify_remove ##### -->
+<para>
+
+</para>
+
+ id: 
 
 
 <!-- ##### FUNCTION lgl_db_get_paper_id_list ##### -->
@@ -40,6 +80,7 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 
 </para>
 
+ void: 
 @Returns: 
 
 
@@ -56,6 +97,7 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 
 </para>
 
+ void: 
 @Returns: 
 
 
@@ -126,6 +168,7 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 
 </para>
 
+ void: 
 @Returns: 
 
 
@@ -142,6 +185,7 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 
 </para>
 
+ void: 
 @Returns: 
 
 
@@ -225,6 +269,25 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 @Returns: 
 
 
+<!-- ##### FUNCTION lgl_db_delete_template_by_brand_part ##### -->
+<para>
+
+</para>
+
+ brand: 
+ part: 
+ Returns: 
+
+
+<!-- ##### FUNCTION lgl_db_delete_template_by_name ##### -->
+<para>
+
+</para>
+
+ name: 
+ Returns: 
+
+
 <!-- ##### FUNCTION lgl_db_does_template_exist ##### -->
 <para>
 
@@ -266,6 +329,15 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 @Returns: 
 
 
+<!-- ##### FUNCTION lgl_db_get_similar_template_name_list ##### -->
+<para>
+
+</para>
+
+ name: 
+ Returns: 
+
+
 <!-- ##### FUNCTION lgl_db_free_template_name_list ##### -->
 <para>
 
@@ -298,6 +370,7 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 
 </para>
 
+ void: 
 @Returns: 
 
 
@@ -332,6 +405,7 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 
 </para>
 
+ void: 
 
 
 <!-- ##### FUNCTION lgl_db_print_known_categories ##### -->
@@ -339,6 +413,7 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 
 </para>
 
+ void: 
 
 
 <!-- ##### FUNCTION lgl_db_print_known_templates ##### -->
@@ -346,6 +421,15 @@ This enumeration defines a set of possible return values for lgl_db_register_tem
 
 </para>
 
+ void: 
+
+
+<!-- ##### FUNCTION lgl_db_print_known_vendors ##### -->
+<para>
+
+</para>
+
+ void: 
 
 
 <!-- ##### FUNCTION lgl_db_print_aliases ##### -->
diff --git a/docs/libglabels/tmpl/paper.sgml b/docs/libglabels/tmpl/paper.sgml
index 448b119..2ceff6f 100644
--- a/docs/libglabels/tmpl/paper.sgml
+++ b/docs/libglabels/tmpl/paper.sgml
@@ -18,6 +18,9 @@ and related functions.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### STRUCT lglPaper ##### -->
 <para>
 This structure defines a paper (page) size.
diff --git a/docs/libglabels/tmpl/str.sgml b/docs/libglabels/tmpl/str.sgml
index e333fb0..3ace130 100644
--- a/docs/libglabels/tmpl/str.sgml
+++ b/docs/libglabels/tmpl/str.sgml
@@ -18,6 +18,9 @@ possible use to a user of libglabels.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### FUNCTION lgl_str_utf8_casecmp ##### -->
 <para>
 
@@ -38,3 +41,12 @@ possible use to a user of libglabels.
 @Returns: 
 
 
+<!-- ##### FUNCTION lgl_str_format_fraction ##### -->
+<para>
+
+</para>
+
+ x: 
+ Returns: 
+
+
diff --git a/docs/libglabels/tmpl/template.sgml b/docs/libglabels/tmpl/template.sgml
index 57e7405..5108840 100644
--- a/docs/libglabels/tmpl/template.sgml
+++ b/docs/libglabels/tmpl/template.sgml
@@ -18,6 +18,9 @@ describes functions to help create and interpret these structures.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### STRUCT lglTemplate ##### -->
 <para>
 This is the main structure of a libglabels template.  A template represents a single sheet
@@ -347,6 +350,16 @@ relative to the upper left corner of the page.
 @Returns: 
 
 
+<!-- ##### FUNCTION lgl_template_are_templates_identical ##### -->
+<para>
+
+</para>
+
+ template1: 
+ template2: 
+ Returns: 
+
+
 <!-- ##### FUNCTION lgl_template_alias_new ##### -->
 <para>
 
@@ -488,6 +501,25 @@ relative to the upper left corner of the page.
 @Returns: 
 
 
+<!-- ##### FUNCTION lgl_template_frame_get_layout_description ##### -->
+<para>
+
+</para>
+
+ frame: 
+ Returns: 
+
+
+<!-- ##### FUNCTION lgl_template_frame_get_size_description ##### -->
+<para>
+
+</para>
+
+ frame: 
+ units: 
+ Returns: 
+
+
 <!-- ##### FUNCTION lgl_template_layout_new ##### -->
 <para>
 
@@ -593,3 +625,11 @@ relative to the upper left corner of the page.
 @markup: 
 
 
+<!-- ##### FUNCTION lgl_template_print ##### -->
+<para>
+
+</para>
+
+ template: 
+
+
diff --git a/docs/libglabels/tmpl/units.sgml b/docs/libglabels/tmpl/units.sgml
index e87eb84..642f3fa 100644
--- a/docs/libglabels/tmpl/units.sgml
+++ b/docs/libglabels/tmpl/units.sgml
@@ -19,6 +19,9 @@ supported by libglabels.  It also defines a set of related functions.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### ENUM lglUnits ##### -->
 <para>
 This enumeration defines supported units of distance.
diff --git a/docs/libglabels/tmpl/vendor.sgml b/docs/libglabels/tmpl/vendor.sgml
index 1dee004..b95d1b9 100644
--- a/docs/libglabels/tmpl/vendor.sgml
+++ b/docs/libglabels/tmpl/vendor.sgml
@@ -17,6 +17,9 @@ This section describes a structure for representing vendor data.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### STRUCT lglVendor ##### -->
 <para>
 This structure defines a vendor.
diff --git a/docs/libglabels/tmpl/xml-category.sgml b/docs/libglabels/tmpl/xml-category.sgml
index f22b59e..8bc90b6 100644
--- a/docs/libglabels/tmpl/xml-category.sgml
+++ b/docs/libglabels/tmpl/xml-category.sgml
@@ -18,6 +18,9 @@ XML category definition files.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### FUNCTION lgl_xml_category_read_categories_from_file ##### -->
 <para>
 
diff --git a/docs/libglabels/tmpl/xml-paper.sgml b/docs/libglabels/tmpl/xml-paper.sgml
index 0909d2c..bb2fd29 100644
--- a/docs/libglabels/tmpl/xml-paper.sgml
+++ b/docs/libglabels/tmpl/xml-paper.sgml
@@ -18,6 +18,9 @@ XML paper definition files.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### FUNCTION lgl_xml_paper_read_papers_from_file ##### -->
 <para>
 
diff --git a/docs/libglabels/tmpl/xml-template.sgml b/docs/libglabels/tmpl/xml-template.sgml
index 3954ff6..e6b6922 100644
--- a/docs/libglabels/tmpl/xml-template.sgml
+++ b/docs/libglabels/tmpl/xml-template.sgml
@@ -19,6 +19,9 @@ template files and document files.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### FUNCTION lgl_xml_template_read_templates_from_file ##### -->
 <para>
 
diff --git a/docs/libglabels/tmpl/xml-vendor.sgml b/docs/libglabels/tmpl/xml-vendor.sgml
index 2550d25..d2e27a9 100644
--- a/docs/libglabels/tmpl/xml-vendor.sgml
+++ b/docs/libglabels/tmpl/xml-vendor.sgml
@@ -17,6 +17,9 @@ This section describes several functions for parsing vendor XML description file
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### FUNCTION lgl_xml_vendor_read_vendors_from_file ##### -->
 <para>
 
diff --git a/docs/libglabels/tmpl/xml.sgml b/docs/libglabels/tmpl/xml.sgml
index e080337..fe1ce1a 100644
--- a/docs/libglabels/tmpl/xml.sgml
+++ b/docs/libglabels/tmpl/xml.sgml
@@ -21,6 +21,9 @@ These functions are basically wrappers to functions from libxml2.
 <!-- ##### SECTION Stability_Level ##### -->
 
 
+<!-- ##### SECTION Image ##### -->
+
+
 <!-- ##### MACRO LGL_XML_NAME_SPACE ##### -->
 <para>
 
diff --git a/libglabels/db.c b/libglabels/db.c
index bbc3209..4f76910 100644
--- a/libglabels/db.c
+++ b/libglabels/db.c
@@ -305,6 +305,15 @@ lgl_db_init (void)
 }
 
 
+/**
+ * lgl_db_notify_add:
+ * @func: Callback function to be called when database changes.
+ * @user_data: Passback user data to supply to callback function.
+ *
+ * Register a notification callback function to be called when the database changes.
+ *
+ * Returns: an ID for this notification registration.
+ */
 gulong
 lgl_db_notify_add (lglDbNotifyFunc func,
                    gpointer        user_data)
@@ -318,6 +327,12 @@ lgl_db_notify_add (lglDbNotifyFunc func,
 }
 
 
+/**
+ * lgl_db_notify_remove:
+ * @id: ID of notification registration to cancel (see lgl_db_notify_add()).
+ *
+ * Cancel a previous registration a notification callback function.
+ */
 void
 lgl_db_notify_remove  (gulong id)
 {
@@ -1526,6 +1541,16 @@ lgl_db_register_template (const lglTemplate *template)
 }
 
 
+/**
+ * lgl_db_delete_template_by_name:
+ * @name:  Name of template to be deleted.
+ *
+ * Delete a user defined template.  This function deletes a template from
+ * the template database. The individual XML file in the user template
+ * directory will also be removed.
+ *
+ * Returns: Status of registration attempt (#lglDbDeleteStatus)
+ */
 lglDbDeleteStatus
 lgl_db_delete_template_by_name (const gchar *name)
 {
@@ -1581,6 +1606,17 @@ lgl_db_delete_template_by_name (const gchar *name)
 }
 
 
+/**
+ * lgl_db_delete_template_by_brand_part:
+ * @brand:  Brand name or vendor of template to be deleted.
+ * @part:   Part name or number of template to be deleted.
+ *
+ * Delete a user defined template.  This function deletes a template from
+ * the template database. The individual XML file in the user template
+ * directory will also be removed.
+ *
+ * Returns: Status of registration attempt (#lglDbDeleteStatus)
+ */
 lglDbDeleteStatus
 lgl_db_delete_template_by_brand_part (const gchar  *brand,
                                       const gchar  *part)
diff --git a/libglabels/str.c b/libglabels/str.c
index f206b2f..a9364c7 100644
--- a/libglabels/str.c
+++ b/libglabels/str.c
@@ -221,9 +221,15 @@ span_non_digits (gchar **p)
 }
 
 
-/****************************************************************************/
-/* Create fractional representation of number, if possible.                 */
-/****************************************************************************/
+/**
+ * lgl_str_format_fraction:
+ * @x: Floating point number to convert to fractional notation
+ *
+ * Create fractional representation of number, if possible.  Uses UTF-8 superscripts and
+ * subscripts for numerator and denominator values respecively.
+ *
+ * Returns: UTF-8 string containing fractional representation of x.
+ */
 gchar *
 lgl_str_format_fraction (gdouble x)
 {
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]