>From 5dbd1e0e80209a8d38e1b4eebab478022ef509ce Mon Sep 17 00:00:00 2001 From: Jon Nordby 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 @@ Goffice Reference Manual For goffice &version; + + + Graphs @@ -194,7 +197,6 @@ - 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 #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: + * + * + * #include + * + * + * 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: + * + * + * pkg-config --libs libgoffice-0.8 + * + * + * + * 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 +/** + * 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 +/** + * 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 #include +/** + * 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 +/** + * 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 +/** + * 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 +/** + * 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 +/** + * 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 +/** + * 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