On Wed, 2010-09-08 at 16:23 +0200, Jon Nordby wrote: > I'm intend to write some short introduction/high-level documentation for > GOffice and add it to the existing gtk-doc based documentation. > Attached is some initial patches, please review. Note that I don't have GNOME git access, so just push it if it looks good.
On my TODO list: - API docs for the things I found unclear when using the library - Example code for most-used parts of graph API Hopefully we can also solve how to document roles and the names/properties of the default plot implementations. With those things solved, we should have a workable experience for users who want to do simple graph stuff with GOffice. I'm on holidays untill monday, so I might not respond before then. -- Regards Jon Nordby - www.jonnor.com Openismus GmbH - www.openismus.com
>From 042e92ddc667df74177bec26bf3b3cc750e7479c Mon Sep 17 00:00:00 2001 From: Jon Nordby <[email protected]> Date: Wed, 15 Sep 2010 16:43:41 +0200 Subject: [PATCH 1/2] Docs: GogText is an abstract class --- docs/reference/goffice-docs.sgml | 3 +-- 1 files changed, 1 insertions(+), 2 deletions(-) diff --git a/docs/reference/goffice-docs.sgml b/docs/reference/goffice-docs.sgml index e3384fe..af072f2 100644 --- a/docs/reference/goffice-docs.sgml +++ b/docs/reference/goffice-docs.sgml @@ -9,7 +9,6 @@ <title>Goffice Reference Manual</title> <releaseinfo>For goffice &version;</releaseinfo> </bookinfo> - <part> <title>Graphs</title> <chapter> @@ -25,7 +24,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 +38,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> -- 1.7.2.2
>From 5dbd1e0e80209a8d38e1b4eebab478022ef509ce Mon Sep 17 00:00:00 2001 From: Jon Nordby <[email protected]> Date: Wed, 15 Sep 2010 18:38:36 +0200 Subject: [PATCH 2/2] Docs: Introduction to GOffice and graphs Adds documentation about GOffice in general, and descriptions to the most relevant objects in the graph API. --- docs/reference/goffice-docs.sgml | 4 ++- goffice/goffice.c | 11 ++++++++++ goffice/goffice.h | 39 ++++++++++++++++++++++++++++++++++++++ goffice/graph/gog-axis.h | 10 +++++++++ goffice/graph/gog-chart.h | 9 ++++++++ goffice/graph/gog-graph.h | 14 +++++++++++++ goffice/graph/gog-label.h | 8 +++++++ goffice/graph/gog-legend.h | 8 +++++++ goffice/graph/gog-object.h | 18 +++++++++++++++++ goffice/graph/gog-plot.h | 15 ++++++++++++++ goffice/graph/gog-renderer.h | 8 +++++++ goffice/graph/gog-series.h | 7 ++++++ 12 files changed, 150 insertions(+), 1 deletions(-) diff --git a/docs/reference/goffice-docs.sgml b/docs/reference/goffice-docs.sgml index af072f2..844f219 100644 --- a/docs/reference/goffice-docs.sgml +++ b/docs/reference/goffice-docs.sgml @@ -9,6 +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> @@ -194,7 +197,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"/> diff --git a/goffice/goffice.c b/goffice/goffice.c index 01addbd..7226e07 100644 --- a/goffice/goffice.c +++ b/goffice/goffice.c @@ -86,6 +86,12 @@ go_sys_lib_dir (void) return libgoffice_lib_dir; } + +/** + * libgoffice_init: + * + * Initialize GOffice. Must be done before using any other GOffice functions. + */ static int initialized = 0; void libgoffice_init (void) @@ -161,6 +167,11 @@ libgoffice_init (void) initialized = TRUE; } +/** + * libgoffice_shutdown: + * + * Shut down GOffice cleanly. + */ void libgoffice_shutdown (void) { diff --git a/goffice/goffice.h b/goffice/goffice.h index c288bbe..a74e310 100644 --- a/goffice/goffice.h +++ b/goffice/goffice.h @@ -59,6 +59,45 @@ #include <goffice/canvas/goffice-canvas.h> #endif +/** + * 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. + */ + G_BEGIN_DECLS void libgoffice_init (void); diff --git a/goffice/graph/gog-axis.h b/goffice/graph/gog-axis.h index 75c5b6e..7d8b938 100644 --- a/goffice/graph/gog-axis.h +++ b/goffice/graph/gog-axis.h @@ -24,6 +24,16 @@ #include <goffice/goffice.h> +/** + * 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". + */ + G_BEGIN_DECLS typedef enum { diff --git a/goffice/graph/gog-chart.h b/goffice/graph/gog-chart.h index 842910e..dc47903 100644 --- a/goffice/graph/gog-chart.h +++ b/goffice/graph/gog-chart.h @@ -24,6 +24,15 @@ #include <goffice/goffice.h> +/** + * 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. +*/ + G_BEGIN_DECLS GogAxisSet gog_axis_set_from_str (char const *str); diff --git a/goffice/graph/gog-graph.h b/goffice/graph/gog-graph.h index a168a92..3642cb8 100644 --- a/goffice/graph/gog-graph.h +++ b/goffice/graph/gog-graph.h @@ -26,6 +26,20 @@ #include <gsf/gsf.h> #include <cairo.h> +/** + * 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". + */ + G_BEGIN_DECLS #define GOG_TYPE_GRAPH (gog_graph_get_type ()) diff --git a/goffice/graph/gog-label.h b/goffice/graph/gog-label.h index c63a5a2..8b2e6a8 100644 --- a/goffice/graph/gog-label.h +++ b/goffice/graph/gog-label.h @@ -24,6 +24,14 @@ #include <goffice/goffice.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. + */ + G_BEGIN_DECLS typedef struct { diff --git a/goffice/graph/gog-legend.h b/goffice/graph/gog-legend.h index 23cefa2..1db81e1 100644 --- a/goffice/graph/gog-legend.h +++ b/goffice/graph/gog-legend.h @@ -23,6 +23,14 @@ #include <goffice/goffice.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. + */ + G_BEGIN_DECLS #define GOG_TYPE_LEGEND (gog_legend_get_type ()) diff --git a/goffice/graph/gog-object.h b/goffice/graph/gog-object.h index d418362..ae8bac9 100644 --- a/goffice/graph/gog-object.h +++ b/goffice/graph/gog-object.h @@ -23,6 +23,24 @@ #include <goffice/goffice.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. + */ + G_BEGIN_DECLS typedef enum { diff --git a/goffice/graph/gog-plot.h b/goffice/graph/gog-plot.h index 768f95e..f09c3c0 100644 --- a/goffice/graph/gog-plot.h +++ b/goffice/graph/gog-plot.h @@ -23,6 +23,21 @@ #include <goffice/goffice.h> +/** + * 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. + */ + G_BEGIN_DECLS typedef struct { diff --git a/goffice/graph/gog-renderer.h b/goffice/graph/gog-renderer.h index 3c0dc5e..c3a1423 100644 --- a/goffice/graph/gog-renderer.h +++ b/goffice/graph/gog-renderer.h @@ -66,6 +66,14 @@ typedef enum #define GOG_RENDERER_CAIRO_WITH_PS #endif +/** + * 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. +*/ + G_BEGIN_DECLS /* We need to define an hair line width for the svg and gnome_print renderer. * 0.5 pt is approx. the dot size of a 150 dpi printer, if the plot is diff --git a/goffice/graph/gog-series.h b/goffice/graph/gog-series.h index dde71f3..5bc93ad 100644 --- a/goffice/graph/gog-series.h +++ b/goffice/graph/gog-series.h @@ -23,6 +23,13 @@ #include <goffice/goffice.h> +/** + * SECTION: gog-series + * @short_description: A single data series. + * + * A #GogSeries represents a data series that can be added to a #GogPlot. + */ + G_BEGIN_DECLS typedef enum { -- 1.7.2.2
_______________________________________________ gnumeric-list mailing list [email protected] http://mail.gnome.org/mailman/listinfo/gnumeric-list
