GNOME.org
 

[goffice] Update API documentation.

commit 2baa5896c31e21370cb52caa0762811cf7f770c2
Author: Jean Brefort <jean brefort normalesup org>
Date:   Mon Sep 20 17:15:03 2010 +0200

    Update API documentation.

 ChangeLog                        |   15 ++++++++++
 NEWS                             |    3 ++
 docs/reference/goffice-docs.sgml |    9 +++---
 goffice/goffice.c                |   55 ++++++++++++++++++++++++++++++++++++++
 goffice/graph/gog-axis.c         |   10 +++++++
 goffice/graph/gog-chart.c        |    9 ++++++
 goffice/graph/gog-graph.c        |   14 +++++++++
 goffice/graph/gog-label.c        |    8 +++++
 goffice/graph/gog-legend.c       |    8 +++++
 goffice/graph/gog-object.c       |   17 +++++++++++
 goffice/graph/gog-plot.c         |   15 ++++++++++
 goffice/graph/gog-renderer.c     |    8 +++++
 goffice/graph/gog-series.c       |    7 +++++
 goffice/gtk/go-graph-widget.c    |    7 +++++
 14 files changed, 181 insertions(+), 4 deletions(-)
---
diff --git a/ChangeLog b/ChangeLog
index 41c9d93..a4d108f 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,18 @@
+2010-09-20  Jon Nordby <jonn openismus com>
+
+	* docs/reference/goffice-docs.sgml: update API documentation.
+	* goffice/goffice.c: ditto.
+	* goffice/graph/gog-axis.c: ditto.
+	* goffice/graph/gog-chart.c: ditto.
+	* goffice/graph/gog-graph.c: ditto.
+	* goffice/graph/gog-label.c: ditto.
+	* goffice/graph/gog-legend.c: ditto.
+	* goffice/graph/gog-object.c: ditto.
+	* goffice/graph/gog-plot.c: ditto.
+	* goffice/graph/gog-renderer.c: ditto.
+	* goffice/graph/gog-series.c: ditto.
+	* goffice/gtk/go-graph-widget.c:
+
 2010-09-10  Morten Welinder  <terra gnome org>
 
 	* goffice/graph/gog-axis.c (map_date_get_dim_format): If we have a
diff --git a/NEWS b/NEWS
index 330f458..ccfbf16 100644
--- a/NEWS
+++ b/NEWS
@@ -1,5 +1,8 @@
 goffice 0.8.11:
 
+Jon Nordby:
+	* Update API documentation.
+
 Morten:
 	* Improve fractional days support for date axes.
 
diff --git a/docs/reference/goffice-docs.sgml b/docs/reference/goffice-docs.sgml
index e3384fe..632ee0d 100644
--- a/docs/reference/goffice-docs.sgml
+++ b/docs/reference/goffice-docs.sgml
@@ -9,7 +9,9 @@
 		<title>Goffice Reference Manual</title>
 		<releaseinfo>For goffice &version;</releaseinfo>
 	</bookinfo>
-
+	<chapter>
+		<xi:include href="xml/goffice.xml"/>
+	</chapter>
 	<part>
 		<title>Graphs</title>
 		<chapter>
@@ -25,7 +27,6 @@
 			<xi:include href="xml/gog-label.xml"/>
 			<xi:include href="xml/gog-reg-eqn.xml"/>
 			<xi:include href="xml/gog-series-lines.xml"/>
-			<xi:include href="xml/gog-text.xml"/>
 		</chapter>
 		<chapter>
 			<title>Abstract Base Classes</title>
@@ -40,6 +41,7 @@
 			<xi:include href="xml/gog-view.xml"/>
 			<xi:include href="xml/gog-data-allocator.xml"/>
 			<xi:include href="xml/gog-data-set.xml"/>
+			<xi:include href="xml/gog-text.xml"/>
 		</chapter>
 		<chapter>
 			<title>Utilities</title>
@@ -84,6 +86,7 @@
 	</part>
 	<part>
 		<title>Widgets</title>
+		<xi:include href="xml/go-graph-widget.xml"/>
 		<chapter>
 			<title>Base widgets</title>
 			<xi:include href="xml/go-combo-box.xml"/>
@@ -195,7 +198,6 @@
 	<xi:include href="xml/go-dock-item.xml"/>
 	<xi:include href="xml/go-dock-item-grip.xml"/>
 </chapter>
-<xi:include href="xml/goffice.xml"/>
 <xi:include href="xml/goffice-priv.xml"/>
 <xi:include href="xml/error-info.xml"/>
 <xi:include href="xml/file-priv.xml"/>
@@ -209,7 +211,6 @@
 <xi:include href="xml/go-action-combo-stack.xml"/>
 <xi:include href="xml/go-action-combo-text.xml"/>
 <xi:include href="xml/go-color-palette.xml"/>
-<xi:include href="xml/go-graph-widget.xml"/>
 <xi:include href="xml/go-marshal.xml"/>
 <xi:include href="xml/goffice-gtk.xml"/>
 <xi:include href="xml/go-ms-parser.xml"/>
diff --git a/goffice/goffice.c b/goffice/goffice.c
index 01addbd..67bfecb 100644
--- a/goffice/goffice.c
+++ b/goffice/goffice.c
@@ -68,6 +68,45 @@ static char const *libgoffice_icon_dir   = GOFFICE_ICONDIR;
 static char const *libgoffice_locale_dir = GOFFICE_LOCALEDIR;
 static char const *libgoffice_lib_dir    = GOFFICE_LIBDIR;
 
+/**
+ * SECTION: goffice
+ * @Title: GOffice
+ *
+ * GOffice is a #GObject based C library. It provides easy API access to
+ * creating and manipulating graphs and canvases. See #GogGraph and #GocCanvas.
+ * It also includes a number of utilities and widgets that might be useful in
+ * office productivity software and similar.
+ *
+ * The GOffice code was originally a part of Gnumeric, but was split into a
+ * separate library in 2005. Today it is being used by projects such as
+ * Gnumeric, Gnucash, Abiword (optional), GChemUtils and more.
+ *
+ * GOffice is cross platform, with support for Windows, OSX, GNU/Linux,
+ * and other Unix-like systems. It can be built with or without GTK+
+ * integration support.
+ *
+ * To include GOffice use:
+ * <informalexample>
+ * <programlisting>
+ * #include <goffice/goffice.h>
+ * </programlisting>
+ * </informalexample>
+ * GOffice provides a pkg-config metadata file named
+ * "libgoffice-$major.$minor.pc", where $major and $minor denote which version
+ * GOffice is. So to link against GOffice 0.8 series, use:
+ * <informalexample>
+ * <programlisting>
+ * pkg-config --libs libgoffice-0.8
+ * </programlisting>
+ * </informalexample>
+ *
+ * API and ABI compatability is maintained per minor release series, e.g:
+ * all 0.8.x releases are ABI/API compatible with previous 0.8.x releases.
+ *
+ * As of September 2010, there are no bindings for other languages
+ * than C available.
+ */
+
 gchar const *
 go_sys_data_dir (void)
 {
@@ -86,6 +125,16 @@ go_sys_lib_dir (void)
 	return libgoffice_lib_dir;
 }
 
+
+/**
+ * libgoffice_init:
+ *
+ * Initialize GOffice.
+ *
+ * This function can be called several times; each call will
+ * increment a reference counter. Code that calls this function should call
+ * libgoffice_shutdown() when done to decrement the counter.
+ */
 static int initialized = 0;
 void
 libgoffice_init (void)
@@ -161,6 +210,12 @@ libgoffice_init (void)
 	initialized = TRUE;
 }
 
+/**
+ * libgoffice_shutdown:
+ *
+ * Decrements the counter for data initialized by libgoffice_init().
+ * When the counter reaches 0, the data is freed/cleaned up as appropriate.
+ */
 void
 libgoffice_shutdown (void)
 {
diff --git a/goffice/graph/gog-axis.c b/goffice/graph/gog-axis.c
index 307192d..4762c67 100644
--- a/goffice/graph/gog-axis.c
+++ b/goffice/graph/gog-axis.c
@@ -33,6 +33,16 @@
 /* this should be per model */
 #define PAD_HACK	4	/* pts */
 
+/**
+ * SECTION: gog-axis
+ * @short_description: An axis.
+ *
+ * An axis of a #GogPlot. The axis handles things like the bounds, ticks, and
+ * tick value formats.
+ * When used in plots with X/Y/Z axes, it can optionally have one
+ * #GogLabel objects in the role "Label".
+ */
+
 static struct {
 	GogAxisPolarUnit unit;
 	const char 	*name;
diff --git a/goffice/graph/gog-chart.c b/goffice/graph/gog-chart.c
index adbd99d..2cd70ed 100644
--- a/goffice/graph/gog-chart.c
+++ b/goffice/graph/gog-chart.c
@@ -50,6 +50,15 @@
 #include <goffice/gtk/goffice-gtk.h>
 #endif
 
+/**
+ * SECTION: gog-chart
+ * @short_description: A chart.
+ * @See_also: #GogPlot
+ *
+ * #GogChart wraps one or more #GogPlot objects, so that you can superimpose
+ * them on top of each other. In addition, the chart can have a title and a legend.
+*/
+
 static const struct {
 	char const *name;
 	GogAxisSet const axis_set;
diff --git a/goffice/graph/gog-graph.c b/goffice/graph/gog-graph.c
index 072af7d..a87fca6 100644
--- a/goffice/graph/gog-graph.c
+++ b/goffice/graph/gog-graph.c
@@ -44,6 +44,20 @@
 #define GOG_GRAPH_DEFAULT_WIDTH 	GO_CM_TO_PT (12.0)
 #define GOG_GRAPH_DEFAULT_HEIGHT 	GO_CM_TO_PT (8.0)
 
+/**
+ * SECTION: gog-graph
+ * @short_description: The graph object.
+ *
+ * A graph (in the abstract sense) in GOffice is an hierarical object model,
+ * with a #GogGraph object as the top-level object.
+ * Objects that can be part of a graph is a subclass of #GogObject. Those, and
+ * related objects have the prefix "Gog" in the class name.
+ * See #GogObject for how to manipulate the object model, and the individual
+ * classes for specifics.
+ *
+ * A #GogGraph can have 1 or more children in the roles "Chart" and "Title".
+ */
+
 enum {
 	GRAPH_PROP_0,
 	GRAPH_PROP_THEME,
diff --git a/goffice/graph/gog-label.c b/goffice/graph/gog-label.c
index a57461d..7c58595 100644
--- a/goffice/graph/gog-label.c
+++ b/goffice/graph/gog-label.c
@@ -26,6 +26,14 @@
 #include <gsf/gsf-impl-utils.h>
 #include <glib/gi18n-lib.h>
 
+/**
+ * SECTION: gog-label
+ * @short_description: A text label.
+ *
+ * A text label for use in a graph.
+ * Can for instance be used as a title of a #GogChart or #GogGraph.
+ */
+
 static GType gog_text_view_get_type (void);
 
 enum {
diff --git a/goffice/graph/gog-legend.c b/goffice/graph/gog-legend.c
index 41ad4fe..0b8a532 100644
--- a/goffice/graph/gog-legend.c
+++ b/goffice/graph/gog-legend.c
@@ -40,6 +40,14 @@
 
 #include <math.h>
 
+/**
+ * SECTION: gog-legend
+ * @short_description: A legend.
+ *
+ * A legend shows the name of each #GogSeries and which colors they
+ * have in the plot. To use, add in the role "Legend" of a #GogChart.
+ */
+
 struct _GogLegend {
 	GogOutlinedObject base;
 
diff --git a/goffice/graph/gog-object.c b/goffice/graph/gog-object.c
index 5500f69..016397d 100644
--- a/goffice/graph/gog-object.c
+++ b/goffice/graph/gog-object.c
@@ -27,6 +27,23 @@
 #include <string.h>
 #include <stdlib.h>
 
+/**
+ * SECTION: gog-object
+ * @short_description: The base class for graph objects.
+ * @See_also: #GogGraph
+ *
+ * Abstract base class that objects in the graph hierarchy are based on.
+ * This class handles manipulation of the object hierarchy, and positioning of
+ * objects in the graph.
+ *
+ * Every object has a name that is unique in the graph. It can have a parent
+ * and a list of children in specific roles (see #GogObjectRole).
+ * There can generally be several children in each role.
+ *
+ * If built with GTK+ support, each object also knows how to populate a widget
+ * that allows one to manipulate the attributes of that object. This can be used
+ * by #GOEditor to present a widget that allows manipulation of the whole graph.
+ */
 
 typedef struct {
 	char const *label;
diff --git a/goffice/graph/gog-plot.c b/goffice/graph/gog-plot.c
index 8228c4e..1613c5e 100644
--- a/goffice/graph/gog-plot.c
+++ b/goffice/graph/gog-plot.c
@@ -45,6 +45,21 @@
 
 #define GOG_PLOT_GET_CLASS(o)	(G_TYPE_INSTANCE_GET_CLASS ((o), GOG_TYPE_PLOT, GogPlotClass))
 
+/**
+ * SECTION: gog-plot
+ * @short_description: A plot.
+ * @See_also: #GogChart, #GogSeries
+ *
+ * This is the object that visualizes data.
+ * To manipulate the data shown in the plot, use gog_plot_new_series() and
+ * gog_plot_clear_series()
+ *
+ * Plots are implemented as plug-ins, so make sure the plug-in system is
+ * initialized before trying to create one. See go_plugins_init()
+ *
+ * GOffice ships a number of common plot implementations by default.
+ */
+
 enum {
 	PLOT_PROP_0,
 	PLOT_PROP_VARY_STYLE_BY_ELEMENT,
diff --git a/goffice/graph/gog-renderer.c b/goffice/graph/gog-renderer.c
index 233b9dc..17a32ee 100644
--- a/goffice/graph/gog-renderer.c
+++ b/goffice/graph/gog-renderer.c
@@ -51,6 +51,14 @@
 
 #include <math.h>
 
+/**
+ * SECTION: gog-renderer
+ * @short_description: Rendering
+ *
+ * Note that #GogGraph has a functions for export/rendering, so you do not always
+ * need to use a #GogRenderer directly.
+*/
+
 enum {
 	RENDERER_PROP_0,
 	RENDERER_PROP_MODEL,
diff --git a/goffice/graph/gog-series.c b/goffice/graph/gog-series.c
index 534744e..ccadb40 100644
--- a/goffice/graph/gog-series.c
+++ b/goffice/graph/gog-series.c
@@ -27,6 +27,13 @@
 
 #include <string.h>
 
+/**
+ * SECTION: gog-series
+ * @short_description: A single data series.
+ *
+ * A #GogSeries represents a data series that can be added to a #GogPlot.
+ */
+
 /* Keep in sync with GogSeriesFillType enum */
 static struct {
 	GogSeriesFillType  type;
diff --git a/goffice/gtk/go-graph-widget.c b/goffice/gtk/go-graph-widget.c
index 5c12180..0c20d86 100644
--- a/goffice/gtk/go-graph-widget.c
+++ b/goffice/gtk/go-graph-widget.c
@@ -30,6 +30,13 @@
 
 static void go_graph_widget_request_update (GOGraphWidget *w);
 
+/**
+ * SECTION: go_graph_widget
+ * @short_description: Widget showing a #GogGraph.
+ *
+ * Utility widget for showing a #GogGraph.
+ */
+
 enum {
 	GRAPH_WIDGET_PROP_0,
 	GRAPH_WIDGET_PROP_ASPECT_RATIO,
[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]