goffice r2122 - in trunk: docs/reference docs/reference/tmpl goffice/app goffice/cut-n-paste/foocanvas goffice/data goffice/graph goffice/gtk goffice/math goffice/utils
- From: jody svn gnome org
- To: svn-commits-list gnome org
- Subject: goffice r2122 - in trunk: docs/reference docs/reference/tmpl goffice/app goffice/cut-n-paste/foocanvas goffice/data goffice/graph goffice/gtk goffice/math goffice/utils
- Date: Sun, 22 Jun 2008 12:30:09 +0000 (UTC)
Author: jody
Date: Sun Jun 22 12:30:08 2008
New Revision: 2122
URL: http://svn.gnome.org/viewvc/goffice?rev=2122&view=rev
Log:
Make gtk-doc happier
Modified:
trunk/docs/reference/goffice-sections.txt
trunk/docs/reference/tmpl/go-color-selector.sgml
trunk/docs/reference/tmpl/gog-control-foocanvas.sgml
trunk/docs/reference/tmpl/gog-graph.sgml
trunk/docs/reference/tmpl/gog-plot.sgml
trunk/docs/reference/tmpl/gog-style.sgml
trunk/goffice/app/file.c
trunk/goffice/app/go-conf-keyfile.c
trunk/goffice/app/go-conf-win32.c
trunk/goffice/app/go-doc.c
trunk/goffice/app/go-plugin.c
trunk/goffice/cut-n-paste/foocanvas/foo-canvas.c
trunk/goffice/data/go-data.c
trunk/goffice/graph/gog-axis.c
trunk/goffice/graph/gog-chart-map.c
trunk/goffice/graph/gog-chart.c
trunk/goffice/graph/gog-data-set.c
trunk/goffice/graph/gog-error-bar.c
trunk/goffice/graph/gog-graph.c
trunk/goffice/graph/gog-guru.c
trunk/goffice/graph/gog-object.c
trunk/goffice/graph/gog-plot.c
trunk/goffice/graph/gog-plot.h
trunk/goffice/graph/gog-series.c
trunk/goffice/graph/gog-theme.c
trunk/goffice/graph/gog-view.c
trunk/goffice/gtk/go-action-combo-stack.c
trunk/goffice/gtk/go-action-combo-text.c
trunk/goffice/gtk/go-color-group.c
trunk/goffice/gtk/go-color-palette.c
trunk/goffice/gtk/go-color-palette.h
trunk/goffice/gtk/go-color-selector.c
trunk/goffice/gtk/go-combo-color.c
trunk/goffice/gtk/go-combo-text.c
trunk/goffice/gtk/go-graph-widget.c
trunk/goffice/gtk/go-selector.c
trunk/goffice/gtk/goffice-gtk.c
trunk/goffice/math/go-regression.c
trunk/goffice/utils/go-file.c
trunk/goffice/utils/go-font.c
trunk/goffice/utils/go-format.c
trunk/goffice/utils/go-geometry.c
trunk/goffice/utils/go-glib-extras.c
trunk/goffice/utils/go-libxml-extras.c
trunk/goffice/utils/go-locale.c
trunk/goffice/utils/go-pattern.c
trunk/goffice/utils/go-undo.c
trunk/goffice/utils/regutf8.c
Modified: trunk/docs/reference/goffice-sections.txt
==============================================================================
--- trunk/docs/reference/goffice-sections.txt (original)
+++ trunk/docs/reference/goffice-sections.txt Sun Jun 22 12:30:08 2008
@@ -335,7 +335,6 @@
GogPlotBoundInfo
gog_plot_new_by_type
gog_plot_new_by_name
-gog_plot_make_similar
gog_plot_request_cardinality_update
gog_plot_get_cardinality
gog_plot_update_cardinality
@@ -421,7 +420,6 @@
<FILE>gog-series-lines</FILE>
<TITLE>GogSeriesLines</TITLE>
GogSeriesLines
-gog_series_lines_render
<SUBSECTION Standard>
GOG_SERIES_LINES_TYPE
GOG_SERIES_LINES
@@ -582,66 +580,6 @@
go_gtk_widget_disable_focus
go_gtk_window_set_transient
go_gtk_editable_enters
-
-<SUBSECTION Dock>
-go_dock_add_floating_item
-go_dock_add_from_layout
-go_dock_add_item
-go_dock_allow_floating_items
-go_dock_band_append
-go_dock_band_drag_begin
-go_dock_band_drag_end
-go_dock_band_drag_to
-go_dock_band_get_child_offset
-go_dock_band_get_item_by_name
-go_dock_band_get_num_children
-go_dock_band_get_orientation
-go_dock_band_get_type
-go_dock_band_insert
-go_dock_band_layout_add
-go_dock_band_move_child
-go_dock_band_new
-go_dock_band_prepend
-go_dock_band_set_child_offset
-go_dock_band_set_orientation
-go_dock_get_client_area
-go_dock_get_item_by_name
-go_dock_get_layout
-go_dock_get_type
-go_dock_item_attach
-go_dock_item_construct
-go_dock_item_detach
-go_dock_item_drag_floating
-go_dock_item_get_behavior
-go_dock_item_get_child
-go_dock_item_get_floating_position
-go_dock_item_get_grip
-go_dock_item_get_name
-go_dock_item_get_orientation
-go_dock_item_get_shadow_type
-go_dock_item_get_type
-go_dock_item_grab_pointer
-go_dock_item_grip_get_type
-go_dock_item_grip_new
-go_dock_item_handle_size_request
-go_dock_item_new
-go_dock_item_set_locked
-go_dock_item_set_orientation
-go_dock_item_set_shadow_type
-go_dock_item_unfloat
-go_dock_layout_add_floating_item
-go_dock_layout_add_item
-go_dock_layout_add_to_dock
-go_dock_layout_create_string
-go_dock_layout_get_item
-go_dock_layout_get_item_by_name
-go_dock_layout_get_type
-go_dock_layout_new
-go_dock_layout_parse_string
-go_dock_layout_remove_item
-go_dock_layout_remove_item_by_name
-go_dock_new
-go_dock_set_client_area
</SECTION>
<SECTION>
@@ -729,7 +667,6 @@
<SECTION>
<FILE>gog-control-foocanvas</FILE>
<TITLE>GogControlFooCanvas</TITLE>
-GogControlFooCanvas
<SUBSECTION Standard>
GOG_CONTROL_FOOCANVAS_TYPE
GOG_CONTROL_FOOCANVAS
@@ -802,7 +739,6 @@
gog_style_set_font_desc
gog_style_set_font
gog_style_set_fill_brightness
-gog_style_set_fill_image_filename
gog_style_set_text_angle
gog_style_is_different_size
gog_style_is_marker_visible
@@ -1990,7 +1926,6 @@
GOServiceSimple
go_service_simple_get_type
<SUBSECTION Private>
-GOServiceSimple
GOServiceSimpleClass
</SECTION>
@@ -2191,8 +2126,3 @@
go_file_saver_set_save_scope
go_file_saver_unregister
</SECTION>
-
-<SECTION>
-<FILE></FILE>
-<TITLE></TITLE>
-</SECTION>
Modified: trunk/docs/reference/tmpl/go-color-selector.sgml
==============================================================================
--- trunk/docs/reference/tmpl/go-color-selector.sgml (original)
+++ trunk/docs/reference/tmpl/go-color-selector.sgml Sun Jun 22 12:30:08 2008
@@ -43,7 +43,7 @@
@no_color_label:
@default_color:
- color_group:
+ cg:
@custom_dialog_title:
@current_color:
@Returns:
@@ -56,7 +56,7 @@
@no_color_label:
@default_color:
- color_group:
+ cg:
@Returns:
Modified: trunk/docs/reference/tmpl/gog-control-foocanvas.sgml
==============================================================================
--- trunk/docs/reference/tmpl/gog-control-foocanvas.sgml (original)
+++ trunk/docs/reference/tmpl/gog-control-foocanvas.sgml Sun Jun 22 12:30:08 2008
@@ -17,29 +17,3 @@
<!-- ##### SECTION Stability_Level ##### -->
-<!-- ##### STRUCT GogControlFooCanvas ##### -->
-<para>
-
-</para>
-
-
-<!-- ##### ARG GogControlFooCanvas:h ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GogControlFooCanvas:model ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GogControlFooCanvas:renderer ##### -->
-<para>
-
-</para>
-
-<!-- ##### ARG GogControlFooCanvas:w ##### -->
-<para>
-
-</para>
-
Modified: trunk/docs/reference/tmpl/gog-graph.sgml
==============================================================================
--- trunk/docs/reference/tmpl/gog-graph.sgml (original)
+++ trunk/docs/reference/tmpl/gog-graph.sgml Sun Jun 22 12:30:08 2008
@@ -39,6 +39,11 @@
@goggraph: the object which received the signal.
@arg1:
+<!-- ##### ARG GogGraph:document ##### -->
+<para>
+
+</para>
+
<!-- ##### ARG GogGraph:height-pts ##### -->
<para>
Modified: trunk/docs/reference/tmpl/gog-plot.sgml
==============================================================================
--- trunk/docs/reference/tmpl/gog-plot.sgml (original)
+++ trunk/docs/reference/tmpl/gog-plot.sgml Sun Jun 22 12:30:08 2008
@@ -80,16 +80,6 @@
@Returns:
-<!-- ##### FUNCTION gog_plot_make_similar ##### -->
-<para>
-
-</para>
-
- dst:
- src:
- Returns:
-
-
<!-- ##### FUNCTION gog_plot_request_cardinality_update ##### -->
<para>
Modified: trunk/docs/reference/tmpl/gog-style.sgml
==============================================================================
--- trunk/docs/reference/tmpl/gog-style.sgml (original)
+++ trunk/docs/reference/tmpl/gog-style.sgml Sun Jun 22 12:30:08 2008
@@ -149,15 +149,6 @@
@brightness:
-<!-- ##### FUNCTION gog_style_set_fill_image_filename ##### -->
-<para>
-
-</para>
-
- style:
- filename:
-
-
<!-- ##### FUNCTION gog_style_set_text_angle ##### -->
<para>
Modified: trunk/goffice/app/file.c
==============================================================================
--- trunk/goffice/app/file.c (original)
+++ trunk/goffice/app/file.c Sun Jun 22 12:30:08 2008
@@ -109,6 +109,8 @@
* @fo : Newly created GOFileOpener object
* @id : Optional ID of the opener (or NULL)
* @description : Description of supported file format
+ * @suffixes : List of suffixes to associate with the opener
+ * @mimes : List of mime types to associate with the opener
* @encoding_dependent: whether the opener depends on an encoding sel.
* @probe_func : Optional pointer to "probe" function (or NULL)
* @open_func : Pointer to "open" function
@@ -116,7 +118,7 @@
* Sets up GOFileOpener object, newly created with g_object_new function.
* This is intended to be used only by GOFileOpener derivates.
* Use go_file_opener_new, if you want to create GOFileOpener object.
- */
+ **/
void
go_file_opener_setup (GOFileOpener *fo, gchar const *id,
gchar const *description,
@@ -142,14 +144,16 @@
* go_file_opener_new:
* @id : Optional ID of the opener (or NULL)
* @description : Description of supported file format
+ * @suffixes : List of suffixes to associate with the opener
+ * @mimes : List of mime types to associate with the opener
* @probe_func : Optional pointer to "probe" function (or NULL)
* @open_func : Pointer to "open" function
*
* Creates new GOFileOpener object. Optional @id will be used
* after registering it with go_file_opener_register function.
*
- * Return value: newly created GOFileOpener object.
- */
+ * Returns: newly created GOFileOpener object.
+ **/
GOFileOpener *
go_file_opener_new (gchar const *id,
gchar const *description,
@@ -171,15 +175,16 @@
* go_file_opener_new_with_enc:
* @id : Optional ID of the opener (or NULL)
* @description : Description of supported file format
+ * @suffixes : List of suffixes to associate with the opener
+ * @mimes : List of mime types to associate with the opener
* @probe_func : Optional pointer to "probe" function (or NULL)
* @open_func : Pointer to "open" function
*
* Creates new GOFileOpener object. Optional @id will be used
* after registering it with go_file_opener_register function.
*
- * Return value: newly created GOFileOpener object.
- */
-
+ * Returns: newly created #GOFileOpener object.
+ **/
GOFileOpener *
go_file_opener_new_with_enc (gchar const *id,
gchar const *description,
@@ -247,14 +252,14 @@
/**
* go_file_opener_probe:
- * @fo : GOFileOpener object
- * @input : The input source
+ * @fo : #GOFileOpener
+ * @input : #GsfInput
+ * @pl : #FileProbeLevel
*
* Checks if a given file is supported by the opener.
*
- * Return value: TRUE, if the opener can read given file and FALSE
- * otherwise.
- */
+ * Returns: %TRUE, if the opener can read given file and %FALSE otherwise.
+ **/
gboolean
go_file_opener_probe (GOFileOpener const *fo, GsfInput *input, FileProbeLevel pl)
{
@@ -551,7 +556,7 @@
* after registering it with go_file_saver_register or
* go_file_saver_register_as_default function.
*
- * Return value: newly created GOFileSaver object.
+ * Returns: newly created GOFileSaver object.
*/
GOFileSaver *
go_file_saver_new (gchar const *id,
@@ -927,7 +932,7 @@
*
* Removes @fs saver from list of available file savers. Reference count
* for the saver is decremented inside the function.
- */
+ **/
void
go_file_saver_unregister (GOFileSaver *fs)
{
@@ -965,12 +970,12 @@
/**
* go_file_saver_get_default:
*
- * Returns file saver registered as default saver with the highest priority.
+ * Finds file saver registered as default saver with the highest priority.
* Reference count for the saver is NOT incremented.
*
- * Return value: GOFileSaver object or NULL if default saver is not
+ * Returns: GOFileSaver object or NULL if default saver is not
* available.
- */
+ **/
GOFileSaver *
go_file_saver_get_default (void)
{
@@ -984,11 +989,8 @@
* go_file_saver_for_mime_type:
* @mime_type: A mime type
*
- * Returns a file saver that claims to save files with given mime type.
- *
- * Return value: GOFileSaver object or NULL if no suitable file saver could
- * be found.
- */
+ * Returns: A #GOFileSaver object associated with @mime_type, or %NULL
+ **/
GOFileSaver *
go_file_saver_for_mime_type (gchar const *mime_type)
{
@@ -1004,12 +1006,12 @@
/**
* go_file_saver_for_file_name :
- * @file_name :
+ * @file_name : name
*
* Searches for file saver with given @filename, registered using
* go_file_opener_register
*
- * Return value: GOFileSaver object or NULL if opener cannot be found.
+ * Returns: GOFileSaver object or NULL if opener cannot be found.
**/
GOFileSaver *
go_file_saver_for_file_name (char const *file_name)
@@ -1025,13 +1027,13 @@
/**
* go_file_opener_for_id:
- * @id : File opener's ID
+ * @id : File opener's ID
*
* Searches for file opener with given @id, registered using
* go_file_opener_register
*
- * Return value: GOFileOpener object or NULL if opener cannot be found.
- */
+ * Returns: #GOFileOpener object or %NULL if opener cannot be found.
+ **/
GOFileOpener *
go_file_opener_for_id (gchar const *id)
{
@@ -1044,13 +1046,13 @@
/**
* go_file_saver_for_id:
- * @id : File saver's ID
+ * @id : File saver's ID
*
* Searches for file saver with given @id, registered using
* go_file_saver_register or register_file_opener_as_default.
*
- * Return value: GOFileSaver object or NULL if saver cannot be found.
- */
+ * Returns: GOFileSaver object or NULL if saver cannot be found.
+ **/
GOFileSaver *
go_file_saver_for_id (gchar const *id)
{
@@ -1064,10 +1066,7 @@
/**
* go_get_file_savers:
*
- * Returns the list of registered file savers (using go_file_saver_register or
- * go_file_saver_register_as_default).
- *
- * Return value: list of GOFileSaver objects, which you shouldn't modify.
+ * Returns: list of known# GOFileSaver types (do not modify list)
*/
GList *
go_get_file_savers (void)
@@ -1078,10 +1077,8 @@
/**
* go_get_file_openers:
*
- * Returns the list of registered file openers (using go_file_opener_register).
- *
- * Return value: list of GOFileOpener objects, which you shouldn't modify.
- */
+ * Returns: list of known #GOFileOpener types (do not modify list)
+ **/
GList *
go_get_file_openers (void)
{
Modified: trunk/goffice/app/go-conf-keyfile.c
==============================================================================
--- trunk/goffice/app/go-conf-keyfile.c (original)
+++ trunk/goffice/app/go-conf-keyfile.c Sun Jun 22 12:30:08 2008
@@ -247,7 +247,7 @@
* @node : #GOConfNode
* @key : non NULL string.
*
- * Returns the string value of @node's @key child as a string which the called needs to free
+ * Returns: the string value of @node's @key child as a string which the called needs to free
**/
gchar *
go_conf_get_string (GOConfNode *node, gchar const *key)
Modified: trunk/goffice/app/go-conf-win32.c
==============================================================================
--- trunk/goffice/app/go-conf-win32.c (original)
+++ trunk/goffice/app/go-conf-win32.c Sun Jun 22 12:30:08 2008
@@ -302,7 +302,7 @@
* @node : #GOConfNode
* @key : non NULL string.
*
- * Returns the string value of @node's @key child as a string which the called needs to free
+ * Returns: the string value of @node's @key child as a string which the called needs to free
**/
gchar *
go_conf_get_string (GOConfNode *node, gchar const *key)
Modified: trunk/goffice/app/go-doc.c
==============================================================================
--- trunk/goffice/app/go-doc.c (original)
+++ trunk/goffice/app/go-doc.c Sun Jun 22 12:30:08 2008
@@ -220,12 +220,12 @@
/**
* go_doc_is_pristine:
- * @doc:
+ * @doc: #GODoc
*
- * This checks to see if the doc has ever been
+ * This checks to see if the doc has ever been
* used ( approximately )
*
- * Return value: TRUE if we can discard this doc.
+ * Return value: %TRUE if we can discard this doc.
**/
gboolean
go_doc_is_pristine (GODoc const *doc)
@@ -334,7 +334,7 @@
static void
init_func (gpointer key, gpointer value, gpointer data)
{
- go_image_init_save ((GOImage*) value);
+ //go_image_init_save ((GOImage*) value);
}
void
Modified: trunk/goffice/app/go-plugin.c
==============================================================================
--- trunk/goffice/app/go-plugin.c (original)
+++ trunk/goffice/app/go-plugin.c Sun Jun 22 12:30:08 2008
@@ -419,7 +419,7 @@
* go_plugin_get_type_module :
* @plugin : #GOPlugin
*
- * Return the GTypeModule associated with the plugin creating it if necessary.
+ * Returns: the GTypeModule associated with the plugin creating it if necessary.
**/
GTypeModule *
go_plugin_get_type_module (GOPlugin *plugin)
@@ -1697,10 +1697,15 @@
/**
* go_plugins_init:
* @context : #GOCmdContext used to report errors
+ * @known_states : A list of known states (defined how ?)
+ * @active_plugins: A list of active plugins
+ * @plugin_dirs :a list of directories to search for plugins
+ * @activate_new_plugins : activate plugins we have no seen before.
+ * @default_loader_type : importer to use by default.
*
* Initializes the plugin subsystem. Don't call this function more than
* once.
- */
+ **/
void
go_plugins_init (GOCmdContext *context,
GSList const *known_states,
@@ -1782,15 +1787,19 @@
/**
* go_plugins_add:
* @context : #GOCmdContext used to report errors
+ * @known_states : A list of known states (defined how ?)
+ * @active_plugins: A list of active plugins
+ * @plugin_dirs :a list of directories to search for plugins
+ * @default_loader_type : importer to use by default.
*
* Adds new plugins to currently used plugins.
- */
+ **/
void
go_plugins_add (GOCmdContext *context,
- GSList const *known_states,
- GSList const *active_plugins,
- GSList *plugin_dirs,
- GType default_loader_type)
+ GSList const *known_states,
+ GSList const *active_plugins,
+ GSList *plugin_dirs,
+ GType default_loader_type)
{
GSList *error_list = NULL;
ErrorInfo *error;
Modified: trunk/goffice/cut-n-paste/foocanvas/foo-canvas.c
==============================================================================
--- trunk/goffice/cut-n-paste/foocanvas/foo-canvas.c (original)
+++ trunk/goffice/cut-n-paste/foocanvas/foo-canvas.c Sun Jun 22 12:30:08 2008
@@ -2176,7 +2176,6 @@
/**
* foo_canvas_new:
- * @void:
*
* Creates a new empty canvas. If you wish to use the
* &FooCanvasImage item inside this canvas, then you must push the gdk_imlib
Modified: trunk/goffice/data/go-data.c
==============================================================================
--- trunk/goffice/data/go-data.c (original)
+++ trunk/goffice/data/go-data.c Sun Jun 22 12:30:08 2008
@@ -97,7 +97,7 @@
* go_data_dup :
* @src : #GOData
*
- * A deep copy of @src.
+ * Returns: A deep copy of @src.
**/
GOData *
go_data_dup (GOData const *src)
@@ -158,10 +158,10 @@
* go_data_as_str :
* @dat : #GOData
*
- * Return a string representation of the data source that the caller is
- * responsible for freeing
- *
* NOTE : This is the _source_ not the content.
+ *
+ * Returns: a string representation of the data source that the caller is
+ * responsible for freeing
**/
char *
go_data_as_str (GOData const *dat)
@@ -174,11 +174,11 @@
/**
* go_data_from_str :
* @dat : #GOData
- * @str :
+ * @str : string to parse
*
* De-serializes the source information returned from go_data_as_str.
*
- * Returns: FALSE on error.
+ * Returns: %FALSE on error.
**/
gboolean
go_data_from_str (GOData *dat, char const *str)
Modified: trunk/goffice/graph/gog-axis.c
==============================================================================
--- trunk/goffice/graph/gog-axis.c (original)
+++ trunk/goffice/graph/gog-axis.c Sun Jun 22 12:30:08 2008
@@ -830,7 +830,7 @@
/**
* gog_axis_map :
* @map : a #GogAxisMap
- * value : value to map to plot space.
+ * @value : value to map to plot space.
*
* Converts @value to plot coordinates. A value in [0,1.0] range means a data
* within axis bounds.
@@ -901,11 +901,10 @@
* gog_axis_map_get_baseline :
* @map : a #GogAxisMap
*
- * Gets the baseline for @map, in view coordinates,
- * clipped to offset and offset+length, where offset and length
- * are the parameters of gog_axis_map_new.
+ * Returns: the baseline for @map, in view coordinates,
+ * clipped to offset and offset+length, where offset and length
+ * are the parameters of gog_axis_map_new.
**/
-
double
gog_axis_map_get_baseline (GogAxisMap *map)
{
@@ -958,9 +957,8 @@
* gog_axis_map_is_inverted:
* @map: a #GogAxisMap
*
- * Accessor to the axis is_inverted property.
+ * Returns: %TRUE is the axis is inverted;
**/
-
gboolean
gog_axis_map_is_inverted (GogAxisMap *map)
{
@@ -1939,10 +1937,10 @@
/**
* gog_axis_get_bounds :
* @axis : #GogAxis
- * @minima : result
- * @maxima : result
+ * @minima : non-NULL storage for result
+ * @maxima : non-NULL storage for result
*
- * return TRUE if the bounds stored in @minima and @maxima are sane
+ * Returns: %TRUE if the bounds stored in @minima and @maxima are sane
**/
gboolean
gog_axis_get_bounds (GogAxis const *axis, double *minima, double *maxima)
Modified: trunk/goffice/graph/gog-chart-map.c
==============================================================================
--- trunk/goffice/graph/gog-chart-map.c (original)
+++ trunk/goffice/graph/gog-chart-map.c Sun Jun 22 12:30:08 2008
@@ -875,9 +875,8 @@
* @n_points: number of points
* @interpolation: interpolation type
*
- * Creates a new GOPath using @x and @y data, each valid point being connected with respect to @interpolation.
+ * Returns: a new GOPath using @x and @y data, each valid point being connected with respect to @interpolation.
**/
-
GOPath *
gog_chart_map_make_path (GogChartMap *map, double const *x, double const *y,
int n_points,
@@ -897,9 +896,8 @@
* @n_points: number of points
* @fill_type: fill type
*
- * Creates a new GOPath using @x and @y data, with respect to @fill_type.
+ * Returns: a new GOPath using @x and @y data, with respect to @fill_type.
**/
-
GOPath *
gog_chart_map_make_close_path (GogChartMap *map, double const *x, double const *y,
int n_points,
Modified: trunk/goffice/graph/gog-chart.c
==============================================================================
--- trunk/goffice/graph/gog-chart.c (original)
+++ trunk/goffice/graph/gog-chart.c Sun Jun 22 12:30:08 2008
@@ -532,8 +532,9 @@
* @chart : #GogChart
* @plot_area : #GogViewAllocation
*
- * Stores plot area in plot_area, in fraction of chart size, and returns
- * TRUE if plot area position is manual.
+ * Stores plot area in plot_area, in fraction of chart size.
+ *
+ * Returns: %TRUE if plot area position is manual.
**/
gboolean
gog_chart_get_plot_area (GogChart *chart, GogViewAllocation *plot_area)
Modified: trunk/goffice/graph/gog-data-set.c
==============================================================================
--- trunk/goffice/graph/gog-data-set.c (original)
+++ trunk/goffice/graph/gog-data-set.c Sun Jun 22 12:30:08 2008
@@ -143,8 +143,12 @@
/**
* gog_dataset_set_dim_internal :
+ * @set : #GogDataset
+ * @dim_i : the index
+ * @val : #GOData
+ * @graph : #GogGraph
*
- * and internal routine to handle signal setup and teardown
+ * an internal routine to handle signal setup and teardown
**/
void
gog_dataset_set_dim_internal (GogDataset *set, int dim_i,
Modified: trunk/goffice/graph/gog-error-bar.c
==============================================================================
--- trunk/goffice/graph/gog-error-bar.c (original)
+++ trunk/goffice/graph/gog-error-bar.c Sun Jun 22 12:30:08 2008
@@ -495,8 +495,8 @@
* -> negative_error in @min.
* If one of the errors is not valid or not defined, its value is set to -1.0.
*
- * Return value : FALSE if the @bar->type is GOG_ERROR_BAR_TYPE_NONE or if the value is not valid,
- * TRUE otherwise.
+ * Returns: %FALSE if the @bar->type is %GOG_ERROR_BAR_TYPE_NONE or if the value is not valid,
+ * %TRUE otherwise.
**/
gboolean
gog_error_bar_get_bounds (GogErrorBar const *bar, int index, double *min, double *max)
Modified: trunk/goffice/graph/gog-graph.c
==============================================================================
--- trunk/goffice/graph/gog-graph.c (original)
+++ trunk/goffice/graph/gog-graph.c Sun Jun 22 12:30:08 2008
@@ -389,7 +389,9 @@
*
* Check the layout of the chart grid and ensure that there are no empty
* cols or rows, and resize as necessary
- */
+ *
+ * Returns: %TRUE if anything changed.
+ **/
gboolean
gog_graph_validate_chart_layout (GogGraph *graph)
{
@@ -477,7 +479,7 @@
* gog_graph_dup :
* @graph : #GogGraph
*
- * A convenience wrapper to make a deep copy of @graph.
+ * Returns: a deep copy of @graph.
**/
GogGraph *
gog_graph_dup (GogGraph const *graph)
@@ -547,9 +549,9 @@
* @graph : #GogGraph
* @dat : #GOData
*
- * If @dat or something equivalent to it already exists in the graph use that.
- * Otherwaise use @dat. Adds a gobject ref to the target and increments a
- * count of the number of refs made from this #GogGraph.
+ * Returns: @dat or something equivalent to it that already exists in the graph.
+ * Otherwise use @dat. Adds a gobject ref to the target and increments a
+ * count of the number of refs made from this #GogGraph.
**/
GOData *
gog_graph_ref_data (GogGraph *graph, GOData *dat)
@@ -917,9 +919,11 @@
* gog_graph_view_handle_event:
* @gview : #GogGraphView
* @event : #GdkEvent
+ * @x_offset : in pixels
+ * @y_offset : in pixels
*
* Handle events.
- */
+ **/
void
gog_graph_view_handle_event (GogGraphView *view, GdkEvent *event,
double x_offset, double y_offset)
Modified: trunk/goffice/graph/gog-guru.c
==============================================================================
--- trunk/goffice/graph/gog-guru.c (original)
+++ trunk/goffice/graph/gog-guru.c Sun Jun 22 12:30:08 2008
@@ -223,11 +223,6 @@
gog_object_add_by_name (GOG_OBJECT (s->chart),
"Plot", GOG_OBJECT (s->plot = plot));
gog_plot_guru_helper (plot);
-#if 0
- if (s->original_plot != NULL &&
- !gog_plot_make_similar (s->plot, s->original_plot))
- return;
-#endif
if (s->dalloc != NULL)
gog_data_allocator_allocate (s->dalloc, s->plot);
Modified: trunk/goffice/graph/gog-object.c
==============================================================================
--- trunk/goffice/graph/gog-object.c (original)
+++ trunk/goffice/graph/gog-object.c Sun Jun 22 12:30:08 2008
@@ -46,11 +46,10 @@
/**
* gog_editor_new:
*
- * Creates a new GogEditor object, which is used to store a
- * collection of property edition widgets (pages). The returned
- * object must be freed using @gog_editor_free.
+ * Returns: a new GogEditor object, which is used to store a collection of
+ * property edition widgets (pages). The returned object must be freed
+ * using @gog_editor_free.
**/
-
GogEditor *
gog_editor_new (void)
{
@@ -165,9 +164,8 @@
* gog_editor_get_notebook:
* @editor: a #GogEditor
*
- * Buils a GtkNotebook from the widget collection stored in @editor.
+ * Returns: a GtkNotebook from the widget collection stored in @editor.
**/
-
GtkWidget *
gog_editor_get_notebook (GogEditor *editor)
{
@@ -1098,6 +1096,8 @@
* @obj : a #GogObject
*
* No need to free the result
+ *
+ * Returns: a name.
**/
char const *
gog_object_get_name (GogObject const *obj)
@@ -1109,7 +1109,7 @@
/**
* gog_object_set_name :
* @obj : #GogObject
- * @name :
+ * @name : The new name for @obj
* @err : #GError
*
* Assign the new name and signals that it has changed.
@@ -1141,7 +1141,8 @@
* @obj : a #GogObject
* @filter : an optional #GogObjectRole to use as a filter
*
- * The list needs to be Freed
+ * Returns: A list of @obj's Children. Caller must free the list, but not the
+ * children.
**/
GSList *
gog_object_get_children (GogObject const *obj, GogObjectRole const *filter)
@@ -1549,6 +1550,8 @@
*
* Does _not_ unref the child, which in effect adds a ref by freeing up the ref
* previously associated with the parent.
+ *
+ * Returns: %TRUE on success.
**/
gboolean
gog_object_clear_parent (GogObject *obj)
@@ -1588,6 +1591,8 @@
* @role: a static string that can be sent to @parent::add
*
* Absorbs a ref to @child
+ *
+ * Returns: %TRUE on success
**/
gboolean
gog_object_set_parent (GogObject *child, GogObject *parent,
@@ -1709,8 +1714,8 @@
* @obj : #GogObject
* @mask : #GogObjectPosition
*
- * Retrieve position flags of GogObject @obj, masked by @mask.
- */
+ * Returns: @obj's position flags, masked by @mask.
+ **/
GogObjectPosition
gog_object_get_position_flags (GogObject const *obj, GogObjectPosition mask)
{
Modified: trunk/goffice/graph/gog-plot.c
==============================================================================
--- trunk/goffice/graph/gog-plot.c (original)
+++ trunk/goffice/graph/gog-plot.c Sun Jun 22 12:30:08 2008
@@ -598,26 +598,16 @@
return res;
}
+/****************************************************************
+ * convenience routines
+ **/
+
/**
- * gog_plot_make_similar :
- * @dst :
- * @src :
- *
- * As much as possible have @dst use similar formatting and data allocation to
- * @src.
+ * gog_plot_new_series :
+ * @plot : #GogPlot
*
- * return TRUE on failue
+ * Returns: a new GogSeries of a type consistent with @plot.
**/
-gboolean
-gog_plot_make_similar (GogPlot *dst, GogPlot const *src)
-{
- g_return_val_if_fail (IS_GOG_PLOT (dst), TRUE);
- g_return_val_if_fail (IS_GOG_PLOT (src), TRUE);
-
- return FALSE;
-}
-
-/* convenience routines */
GogSeries *
gog_plot_new_series (GogPlot *plot)
{
@@ -793,7 +783,7 @@
* gog_plot_get_series :
* @plot : #GogPlot
*
- * A list of the series in @plot. Do not modify or free the list.
+ * Returns: A list of the series in @plot. Do not modify or free the list.
**/
GSList const *
gog_plot_get_series (GogPlot const *plot)
@@ -815,6 +805,8 @@
* the lookup too if so desired.
*
* Caller is responsible for unrefing ::fmt.
+ *
+ * Returns: The data providing the bound (does not add a ref)
**/
GOData *
gog_plot_get_axis_bounds (GogPlot *plot, GogAxisType axis,
Modified: trunk/goffice/graph/gog-plot.h
==============================================================================
--- trunk/goffice/graph/gog-plot.h (original)
+++ trunk/goffice/graph/gog-plot.h Sun Jun 22 12:30:08 2008
@@ -44,7 +44,6 @@
GType gog_plot_get_type (void);
GogPlot *gog_plot_new_by_type (GogPlotType const *type);
GogPlot *gog_plot_new_by_name (char const *id);
-gboolean gog_plot_make_similar (GogPlot *dst, GogPlot const *src);
void gog_plot_request_cardinality_update (GogPlot *plot);
void gog_plot_update_cardinality (GogPlot *plot, int index_num);
Modified: trunk/goffice/graph/gog-series.c
==============================================================================
--- trunk/goffice/graph/gog-series.c (original)
+++ trunk/goffice/graph/gog-series.c Sun Jun 22 12:30:08 2008
@@ -828,10 +828,10 @@
/**
* gog_series_set_index :
* @series: #GogSeries
- * @ind:
- * @is_manual:
+ * @ind: >= 0 assigns a new index, < 0 resets to auto
+ * @is_manual: gboolean
*
- * If @index >= 0 attempt to assign the new index. Auto
+ * If @ind >= 0 attempt to assign the new index. Auto
* indicies (@is_manual == FALSE) will not override the current
* index if it is manual. An @index < 0, will reset the index to
* automatic and potentially queue a revaluation of the parent
@@ -893,7 +893,7 @@
/**
* gog_series_set_dim :
* @series : #GogSeries
- * @dim_i :
+ * @dim_i : Which dimension
* @val : #GOData
* @err : optional #Gerror pointer
*
Modified: trunk/goffice/graph/gog-theme.c
==============================================================================
--- trunk/goffice/graph/gog-theme.c (original)
+++ trunk/goffice/graph/gog-theme.c Sun Jun 22 12:30:08 2008
@@ -410,11 +410,11 @@
/**
* gog_theme_registry_add:
* @theme: a #GogTheme
+ * @is_default : bool
*
* Keep a pointer to @theme in graph theme registry.
* This function does not add a reference to @theme.
**/
-
void
gog_theme_registry_add (GogTheme *theme, gboolean is_default)
{
@@ -437,9 +437,8 @@
* gog_theme_registry_lookup:
* @name: a theme name
*
- * Retrieves a #GogTheme from theme registry.
+ * Returns: a #GogTheme from theme registry.
**/
-
GogTheme *
gog_theme_registry_lookup (char const *name)
{
Modified: trunk/goffice/graph/gog-view.c
==============================================================================
--- trunk/goffice/graph/gog-view.c (original)
+++ trunk/goffice/graph/gog-view.c Sun Jun 22 12:30:08 2008
@@ -940,8 +940,11 @@
/**
* gog_view_get_tool_at_point:
* @view : #GogView
+ * @x : in coords
+ * @y : in coords
+ * @gobj : non-%NULL storage.
*
- * Find tool under cursor for a given view.
+ * Returns: tool under cursor for a given view, or %NULL
**/
GogTool *
gog_view_get_tool_at_point (GogView *view, double x, double y, GogObject **gobj)
Modified: trunk/goffice/gtk/go-action-combo-stack.c
==============================================================================
--- trunk/goffice/gtk/go-action-combo-stack.c (original)
+++ trunk/goffice/gtk/go-action-combo-stack.c Sun Jun 22 12:30:08 2008
@@ -429,7 +429,7 @@
/**
* go_action_combo_stack_pop :
* @act : #GOActionComboStack
- * @n :
+ * @n : count
*
* Shorten list @act by removing @n off the top (or fewer if the list is
* shorter)
@@ -453,7 +453,7 @@
/**
* go_action_combo_stack_truncate :
* @act : #GOActionComboStack
- * @n :
+ * @n : maximum length
*
* Ensure that list @act is no longer than @n, dropping any extra off the
* bottom.
Modified: trunk/goffice/gtk/go-action-combo-text.c
==============================================================================
--- trunk/goffice/gtk/go-action-combo-text.c (original)
+++ trunk/goffice/gtk/go-action-combo-text.c Sun Jun 22 12:30:08 2008
@@ -281,9 +281,9 @@
/**
* go_action_combo_text_set_entry :
- * @taction :
- * @text :
- * @dir :
+ * @taction : @GOActionComboText
+ * @text : the new text
+ * @dir : #GOActionComboTextSearchDir
*
* Set the entry of any toolbar proxies of @taction to @text. Does not
* generate an 'activate' signal.
Modified: trunk/goffice/gtk/go-color-group.c
==============================================================================
--- trunk/goffice/gtk/go-color-group.c (original)
+++ trunk/goffice/gtk/go-color-group.c Sun Jun 22 12:30:08 2008
@@ -97,12 +97,13 @@
/**
* go_color_group_find :
- * @name :
- * @context :
+ * @name : target name
+ * @context : an arbitrary id to identify what context to search in
*
- * Look up the name/context specific color-group. Return NULL if it is not found.
* No reference is added if it is found.
- */
+ * Returns: Look up the name/context specific color-group.
+ * %NULL if it is not found.
+ **/
GOColorGroup *
go_color_group_find (char const *name, gpointer context)
{
@@ -136,8 +137,8 @@
/**
* go_color_group_fetch :
- * @name :
- * @context :
+ * @name : target name
+ * @context : identifying context
*
* if name is NULL or a name not currently in use by another group
* then a new group is created and returned. If name was NULL
@@ -145,9 +146,11 @@
* (thereby insuring namespace separation).
* If name was already used by a group then the reference count is
* incremented and a pointer to the group is returned.
- */
+ *
+ * Returns: A #GOColorGroup
+ **/
GOColorGroup *
-go_color_group_fetch (const gchar *name, gpointer context)
+go_color_group_fetch (char const *name, gpointer context)
{
GOColorGroup *cg;
gchar *new_name;
Modified: trunk/goffice/gtk/go-color-palette.c
==============================================================================
--- trunk/goffice/gtk/go-color-palette.c (original)
+++ trunk/goffice/gtk/go-color-palette.c Sun Jun 22 12:30:08 2008
@@ -388,30 +388,32 @@
/**
* go_color_palette_set_group :
+ * @p : #GOColorPalette
* @cg : #GOColorGroup
*
- * Absorb the reference to the group
- */
+ * Absorbs the reference to the group
+ **/
void
-go_color_palette_set_group (GOColorPalette *pal, GOColorGroup *cg)
+go_color_palette_set_group (GOColorPalette *p, GOColorGroup *cg)
{
- if (pal->group == cg)
+ if (p->group == cg)
return;
- if (pal->group) {
+ if (p->group) {
g_signal_handlers_disconnect_by_func (
- G_OBJECT (pal->group),
- G_CALLBACK (cb_history_changed), pal);
- g_object_unref (G_OBJECT (pal->group));
- pal->group = NULL;
+ G_OBJECT (p->group),
+ G_CALLBACK (cb_history_changed), p);
+ g_object_unref (G_OBJECT (p->group));
+ p->group = NULL;
}
if (cg != NULL) {
- pal->group = cg;
+ p->group = cg;
g_signal_connect_swapped (G_OBJECT (cg),
"history-changed",
- G_CALLBACK (cb_history_changed), pal);
+ G_CALLBACK (cb_history_changed), p);
}
}
+
static GtkWidget *
go_color_palette_setup (GOColorPalette *pal,
char const *no_color_label,
@@ -496,10 +498,18 @@
pal->allow_alpha = allow_alpha;
}
+/**
+ * go_color_palette_new:
+ * @no_color_label: color label
+ * @default_color: #GOColor
+ * @cg: #GOColorGroup
+ *
+ * Returns: A new palette
+ **/
GtkWidget *
go_color_palette_new (char const *no_color_label,
- GOColor default_color,
- GOColorGroup *cg)
+ GOColor default_color,
+ GOColorGroup *cg)
{
GOColorPalette *pal;
int const cols = 8;
@@ -632,13 +642,13 @@
/**
* go_color_palette_make_menu:
* @no_color_label: color label
- * default_color: #GOColor
- * @color_group: #GOColorGroup
- * @custom_dialog_title :
+ * @default_color: #GOColor
+ * @cg: #GOColorGroup
+ * @custom_dialog_title : optional string
* @current_color : #GOColor
*
- * Create a submenu with a palette of colours. Caller is responsible for
- * creating an item to point to the submenu.
+ * Returns: a submenu with a palette of colours. Caller is responsible for
+ * creating an item to point to the submenu.
**/
GtkWidget *
go_color_palette_make_menu (char const *no_color_label,
Modified: trunk/goffice/gtk/go-color-palette.h
==============================================================================
--- trunk/goffice/gtk/go-color-palette.h (original)
+++ trunk/goffice/gtk/go-color-palette.h Sun Jun 22 12:30:08 2008
@@ -46,10 +46,10 @@
GtkWidget *go_color_palette_new (char const *no_color_label,
GOColor default_color,
- GOColorGroup *color_group);
+ GOColorGroup *cg);
GtkWidget *go_color_palette_make_menu (char const *no_color_label,
GOColor default_color,
- GOColorGroup *color_group,
+ GOColorGroup *cg,
char const *custom_dialog_title,
GOColor current_color);
Modified: trunk/goffice/gtk/go-color-selector.c
==============================================================================
--- trunk/goffice/gtk/go-color-selector.c (original)
+++ trunk/goffice/gtk/go-color-selector.c Sun Jun 22 12:30:08 2008
@@ -352,12 +352,13 @@
/**
* go_color_selector_get_color:
* @selector: a #GOSelector
+ * @is_auto : non-NULL result storage
*
* Retrieves current color selection of a #GOSelector
* created via @go_color_selector_new. @is_auto will be set to
* TRUE if current selection was set by clicking on automatic palette item.
*
- * return current color selection.
+ * Returns: current color selection.
**/
GOColor
go_color_selector_get_color (GOSelector *selector, gboolean *is_auto)
@@ -384,7 +385,7 @@
/**
* go_color_selector_set_allow_alpha :
* @selector : #GOColorSelector
- * @allow_alpha :
+ * @allow_alpha : boolean
*
* Should the custom colour selector allow the use of opacity.
**/
Modified: trunk/goffice/gtk/go-combo-color.c
==============================================================================
--- trunk/goffice/gtk/go-combo-color.c (original)
+++ trunk/goffice/gtk/go-combo-color.c Sun Jun 22 12:30:08 2008
@@ -239,8 +239,10 @@
}
/* go_combo_color_get_color:
+ * @cc: #GOComboColor
+ * @is_default : non-NULL storage for whether the current colour is the default.
*
- * Return current color
+ * Returns: current GOColor
*/
GOColor
go_combo_color_get_color (GOComboColor *cc, gboolean *is_default)
@@ -271,10 +273,9 @@
/**
* go_combo_color_set_color :
- * @cc: a #GOComboColor
+ * @cc: #GOComboColor
* @color: a #GOColor
**/
-
void
go_combo_color_set_color (GOComboColor *cc, GOColor c)
{
@@ -283,7 +284,7 @@
/**
* go_combo_color_set_instant_apply :
- * @cc: The combo
+ * @cc: #GOComboColor
* @active: Whether instant apply should be active or not
*
* Turn instant apply behaviour on or off. Instant apply means that pressing
@@ -301,7 +302,7 @@
/**
* go_combo_color_set_allow_alpha :
* @cc : #GOComboColor
- * @allow_alpha :
+ * @allow_alpha : Support alpha layer
*
* Should the custom colour selector allow the use of opacity.
**/
@@ -313,7 +314,7 @@
/**
* go_combo_color_set_color_to_default :
- * @cc: The combo
+ * @cc: #GOComboColor
*
* Set the color of the combo to the default color. Causes the color_changed
* signal to be emitted.
@@ -330,10 +331,14 @@
* go_combo_color_new :
* @icon: optionally NULL.
* @no_color_label: FIXME
+ * @default_color : The colour to use a the default
+ * @color_group : #GOColorGroup
*
* Default constructor. Pass an optional icon and an optional label for the
* no/auto color button.
- */
+ *
+ * Returns: The newly constructed combo.
+ **/
GtkWidget *
go_combo_color_new (GdkPixbuf *icon, char const *no_color_label,
GOColor default_color,
Modified: trunk/goffice/gtk/go-combo-text.c
==============================================================================
--- trunk/goffice/gtk/go-combo-text.c (original)
+++ trunk/goffice/gtk/go-combo-text.c Sun Jun 22 12:30:08 2008
@@ -310,14 +310,14 @@
/**
* go_combo_text_set_text :
- * @ct :
+ * @ct : #GoComboText
* @text : the label for the new item
* @start : where to begin the search in the list.
*
- * return TRUE if the item is found in the list.
+ * Returns: %TRUE if the item is found in the list.
*/
gboolean
-go_combo_text_set_text (GoComboText *ct, const gchar *text,
+go_combo_text_set_text (GoComboText *ct, gchar const *text,
GoComboTextSearch start)
{
gboolean found = FALSE, result;
Modified: trunk/goffice/gtk/go-graph-widget.c
==============================================================================
--- trunk/goffice/gtk/go-graph-widget.c (original)
+++ trunk/goffice/gtk/go-graph-widget.c Sun Jun 22 12:30:08 2008
@@ -362,6 +362,10 @@
/**
* go_graph_widget_set_size_mode :
+ * @widget : #GOGraphWidget
+ * @size_mode : #GOGraphWidgetSizeMode
+ * @width : in pixels
+ * @height : in pixels
*
* Sets the size mode of the #GOGraphWidget.
* It is used to determine the size and position of the drawn
@@ -389,7 +393,7 @@
* GO_GRAPH_WIDGET_SIZE_MODE_FIT_FIXED_SIZE, no aspect ratio set.
* The graph will occupy the area specified by width/height,
* its aspect ratio will be determined by height/width.
- */
+ **/
void
go_graph_widget_set_size_mode (GOGraphWidget *widget,
GOGraphWidgetSizeMode size_mode,
@@ -413,6 +417,7 @@
/**
* go_graph_widget_new :
+ * @graph : #GogGraph
*
* Creates a new #GOGraphWidget with an embedded #GogGraph.
* If graph is NULL, the graph will be auto-created, and a
Modified: trunk/goffice/gtk/go-selector.c
==============================================================================
--- trunk/goffice/gtk/go-selector.c (original)
+++ trunk/goffice/gtk/go-selector.c Sun Jun 22 12:30:08 2008
@@ -406,7 +406,7 @@
/**
* go_selector_get_active:
* @selector: a #GOSelector
- * @is_auto :
+ * @is_auto : boolean
*
* Retrieves current selection index, and set @is_auto to TRUE if
* current selection was set by clicking on automatic palette item.
Modified: trunk/goffice/gtk/goffice-gtk.c
==============================================================================
--- trunk/goffice/gtk/goffice-gtk.c (original)
+++ trunk/goffice/gtk/goffice-gtk.c Sun Jun 22 12:30:08 2008
@@ -48,15 +48,13 @@
/**
* go_gtk_button_new_with_stock
+ * @text : button label
+ * @stock_id : id for stock icon
*
- * Code from gedit
- *
+ * FROM : gedit
* Creates a new GtkButton with custom label and stock image.
*
- * text : button label
- * stock_id : id for stock icon
- *
- * return : newly created button
+ * Returns: newly created button
**/
GtkWidget*
go_gtk_button_new_with_stock (char const *text, char const* stock_id)
@@ -76,13 +74,13 @@
* @stock_id: stock icon id
* @response_id: respond id when button clicked
*
+ * FROM : gedit
* Creates and adds a button with stock image to the action area of an existing dialog.
- * Code from gedit
*
- * return : newly created button
+ * Returns: newly created button
**/
GtkWidget*
-go_gtk_dialog_add_button (GtkDialog *dialog, const gchar* text, const gchar* stock_id,
+go_gtk_dialog_add_button (GtkDialog *dialog, char const* text, char const* stock_id,
gint response_id)
{
GtkWidget *button;
@@ -106,11 +104,13 @@
/**
* go_glade_new :
* @gcc : #GOCmdContext
- * @gladefile :
+ * @gladefile : the name of the file load
*
* Simple utility to open glade files
*
* 0.4.3 : renamed from go_libglade_new
+ *
+ * Returns: a new #GladeXML or NULL
**/
GladeXML *
go_glade_new (char const *gladefile, char const *root,
@@ -140,12 +140,14 @@
/**
* go_glade_signal_connect :
* @gui : #GladeXML
- * @instance_name :
- * @detailed_signal :
+ * @instance_name : widget name
+ * @detailed_signal : signal name
* @c_handle : #GCallback
- * @data :
+ * @data : arbitrary
*
* Convenience wrapper around g_signal_connect for glade.
+ *
+ * Returns: The signal id
**/
gulong
go_glade_signal_connect (GladeXML *gui,
@@ -164,12 +166,14 @@
/**
* go_glade_signal_connect :
* @gui : #GladeXML
- * @instance_name :
- * @detailed_signal :
+ * @instance_name : widget name
+ * @detailed_signal : signal name
* @c_handle : #GCallback
- * @data :
+ * @data : arbitary
*
* Convenience wrapper around g_signal_connect_swapped for glade.
+ *
+ * Returns: The signal id
**/
gulong
go_glade_signal_connect_swapped (GladeXML *gui,
@@ -185,7 +189,6 @@
return g_signal_connect_swapped (w, detailed_signal, c_handler, data);
}
-
/*
* A variant of gtk_window_activate_default that does not end up reactivating
* the widget that [Enter] was pressed in.
@@ -199,8 +202,8 @@
/**
* go_gtk_editable_enters:
- * @window:
- * @w:
+ * @window: #GtkWindow
+ * @w: #GtkWidget
*
* Normally if there's an editable widget (such as #GtkEntry) in your
* dialog, pressing Enter will activate the editable rather than the
@@ -217,6 +220,12 @@
G_CALLBACK (cb_activate_default), window);
}
+/**
+ * go_gtk_widget_disable_focus :
+ * @w : #GtkWidget
+ *
+ * Convenience wrapper to disable focus on a container and it's children.
+ **/
void
go_gtk_widget_disable_focus (GtkWidget *w)
{
@@ -226,8 +235,18 @@
GTK_WIDGET_UNSET_FLAGS (w, GTK_CAN_FOCUS);
}
+/**
+ * go_pango_measure_string :
+ * @context : #PangoContext
+ * @font_desc : #PangoFontDescription
+ * @str : The text to measure.
+ *
+ * A utility function to measure text.
+ *
+ * Returns: the pixel length of @str according to @context.
+ **/
int
-go_pango_measure_string (PangoContext *context, const PangoFontDescription *font_desc, const char *str)
+go_pango_measure_string (PangoContext *context, PangoFontDescription const *font_desc, char const *str)
{
PangoLayout *layout = pango_layout_new (context);
int width;
@@ -260,7 +279,7 @@
* one. The function duplicates the positioning functionality in
* gnome_dialog_set_parent, but does not require the transient window to be
* a GnomeDialog.
- */
+ **/
void
go_gtk_window_set_transient (GtkWindow *toplevel, GtkWindow *window)
{
@@ -296,6 +315,14 @@
return FALSE;
}
+/**
+ * go_gtk_nonmodal_dialog :
+ * @toplevel : #GtkWindow
+ * @dialog : #GtkWindow
+ *
+ * Utility to set @dialog as a transient of @toplevel
+ * and to set up a handler for <ESC>
+ **/
void
go_gtk_nonmodal_dialog (GtkWindow *toplevel, GtkWindow *dialog)
{
@@ -331,6 +358,15 @@
return TRUE; /* Do not destroy */
}
+/**
+ * go_gtk_file_sel_dialog :
+ * @toplevel : #GtkWindow
+ * @w : #GtkWidget
+ *
+ * Runs a modal dialog to select a file.
+ *
+ * Returns: %TRUE if a file was selected.
+ **/
gboolean
go_gtk_file_sel_dialog (GtkWindow *toplevel, GtkWidget *w)
{
@@ -367,7 +403,7 @@
if (filter_info->display_name) {
GSList *l;
- const char *ext = strrchr (filter_info->display_name, '.');
+ char const *ext = strrchr (filter_info->display_name, '.');
if (!ext) return FALSE;
ext++;
@@ -511,9 +547,9 @@
}
char *
-go_gtk_select_image (GtkWindow *toplevel, const char *initial)
+go_gtk_select_image (GtkWindow *toplevel, char const *initial)
{
- const char *key = "go_gtk_select_image";
+ char const *key = "go_gtk_select_image";
char *uri = NULL;
GtkFileChooser *fsel;
@@ -589,7 +625,7 @@
GtkWidget *resolution_table;
GladeXML *gui;
SaveInfoState *state;
- const char *key = "go_gui_get_image_save_info";
+ char const *key = "go_gui_get_image_save_info";
char *uri = NULL;
state = g_object_get_data (G_OBJECT (toplevel), key);
@@ -841,7 +877,7 @@
* go_gtk_url_is_writeable:
* @parent : #GtkWindow
* @uri : the uri to test.
- * @overwrite_by_default :
+ * @overwrite_by_default : gboolean
*
* Check if it makes sense to try saving.
* If it's an existing file and writable for us, ask if we want to overwrite.
@@ -850,6 +886,8 @@
*
* FIXME: The message boxes should really be children of the file selector,
* not the workbook.
+ *
+ * Returns: %TRUE if @url is writable
**/
gboolean
go_gtk_url_is_writeable (GtkWindow *parent, char const *uri,
@@ -902,9 +940,13 @@
/**
* go_gtk_dialog_run
+ * @dialog : #GtkDialog
+ * @parent : #GtkWindow
*
* Pop up a dialog as child of a window.
- */
+ *
+ * Returns: result ID.
+ **/
gint
go_gtk_dialog_run (GtkDialog *dialog, GtkWindow *parent)
{
@@ -941,7 +983,7 @@
*/
void
go_gtk_notice_dialog (GtkWindow *parent, GtkMessageType type,
- const gchar *format, ...)
+ char const *format, ...)
{
va_list args;
gchar *msg;
@@ -957,7 +999,7 @@
void
go_gtk_notice_nonmodal_dialog (GtkWindow *parent, GtkWidget **ref,
- GtkMessageType type, const gchar *format, ...)
+ GtkMessageType type, char const *format, ...)
{
va_list args;
gchar *msg;
@@ -983,7 +1025,7 @@
gboolean
go_gtk_query_yes_no (GtkWindow *parent, gboolean default_answer,
- const gchar *format, ...)
+ char const *format, ...)
{
va_list args;
gchar *msg;
@@ -1027,7 +1069,7 @@
#endif
void
-go_widget_set_tooltip_text (GtkWidget *widget, const gchar *tip)
+go_widget_set_tooltip_text (GtkWidget *widget, char const *tip)
{
#ifdef HAVE_GTK_WIDGET_SET_TOOLTIP_TEXT
gtk_widget_set_tooltip_text (widget, tip);
@@ -1038,7 +1080,7 @@
}
void
-go_tool_item_set_tooltip_text (GtkToolItem *item, const gchar *tip)
+go_tool_item_set_tooltip_text (GtkToolItem *item, char const *tip)
{
#ifdef HAVE_GTK_TOOL_ITEM_SET_TOOLTIP_TEXT
gtk_tool_item_set_tooltip_text (item, tip);
@@ -1054,9 +1096,9 @@
static gint
gtk_dialog_get_response_for_widget (GtkDialog *dialog, GtkWidget *widget)
{
- const struct {
+ struct {
gint response_id;
- } *rd = g_object_get_data (G_OBJECT (widget),
+ } const *rd = g_object_get_data (G_OBJECT (widget),
"gtk-dialog-response-data");
if (!rd)
return GTK_RESPONSE_NONE;
@@ -1068,7 +1110,7 @@
/**
* go_dialog_guess_alternative_button_order:
- * @dialog :
+ * @dialog : #GtkDialog
*
* This function inspects the buttons in the dialog and comes up
* with a reasonable alternative dialog order.
@@ -1141,15 +1183,14 @@
/**
* go_menu_position_below:
* @menu: a #GtkMenu
- * @x:
- * @y:
- * @push_in:
- * @user_data:
+ * @x: non-NULL storage for the X coordinate of the menu
+ * @y: non-NULL storage for the Y coordinate of the menu
+ * @push_in: non-NULL storage for the push-in distance
+ * @user_data: arbitrary
*
* Implementation of a GtkMenuPositionFunc that positions
* the child window under the parent one, for use with gtk_menu_popup.
**/
-
void
go_menu_position_below (GtkMenu *menu,
gint *x,
Modified: trunk/goffice/math/go-regression.c
==============================================================================
--- trunk/goffice/math/go-regression.c (original)
+++ trunk/goffice/math/go-regression.c Sun Jun 22 12:30:08 2008
@@ -804,13 +804,13 @@
* @n: number of data points.
* @affine: if true, a non-zero constant is allowed.
* @res: output place for constant[0] and slope1[1], slope2[2],... There will be dim+1 results.
+ * @stat : non-NULL storage for additional results.
*
* Performs multi-dimensional linear regressions on the input points.
* Fits to "y = b + a1 * x1 + ... ad * xd".
*
* Returns: #RegressionResult as above.
**/
-
RegressionResult
SUFFIX(go_linear_regression) (DOUBLE **xss, int dim,
const DOUBLE *ys, int n,
@@ -848,6 +848,7 @@
* @n: number of data points
* @affine: if %TRUE, a non-one multiplier is allowed
* @res: output place for constant[0] and root1[1], root2[2],... There will be dim+1 results.
+ * @stat : non-NULL storage for additional results.
*
* Performs one-dimensional linear regressions on the input points.
* Fits to "y = b * m1^x1 * ... * md^xd " or equivalently to
@@ -855,7 +856,6 @@
*
* Returns: #RegressionResult as above.
**/
-
RegressionResult
SUFFIX(go_exponential_regression) (DOUBLE **xss, int dim,
const DOUBLE *ys, int n,
@@ -911,6 +911,7 @@
* @n: number of data points
* @affine: if %TRUE, a non-one multiplier is allowed
* @res: output place for constant[0] and root1[1], root2[2],... There will be dim+1 results.
+ * @stat : non-NULL storage for additional results.
*
* Performs one-dimensional linear regressions on the input points.
* Fits to "y = b * x1^m1 * ... * xd^md " or equivalently to
@@ -918,7 +919,6 @@
*
* Returns: #RegressionResult as above.
**/
-
RegressionResult
SUFFIX(go_power_regression) (DOUBLE **xss, int dim,
const DOUBLE *ys, int n,
@@ -983,6 +983,7 @@
* @n: number of data points
* @affine: if %TRUE, a non-zero constant is allowed
* @res: output place for constant[0] and factor1[1], factor2[2],... There will be dim+1 results.
+ * @stat : non-NULL storage for additional results.
*
* This is almost a copy of linear_regression and produces multi-dimensional
* linear regressions on the input points after transforming xss to ln(xss).
@@ -994,7 +995,6 @@
*
* Returns: #RegressionResult as above.
**/
-
RegressionResult
SUFFIX(go_logarithmic_regression) (DOUBLE **xss, int dim,
const DOUBLE *ys, int n,
Modified: trunk/goffice/utils/go-file.c
==============================================================================
--- trunk/goffice/utils/go-file.c (original)
+++ trunk/goffice/utils/go-file.c Sun Jun 22 12:30:08 2008
@@ -59,7 +59,7 @@
* Convert an escaped URI into a filename.
*/
char *
-go_filename_from_uri (const char *uri)
+go_filename_from_uri (char const *uri)
{
#ifdef GOFFICE_WITH_GNOME
return gnome_vfs_get_local_path_from_uri (uri);
@@ -72,7 +72,7 @@
* Convert a filename into an escaped URI.
*/
char *
-go_filename_to_uri (const char *filename)
+go_filename_to_uri (char const *filename)
{
char *simp, *uri;
@@ -90,7 +90,7 @@
}
char *
-go_filename_simplify (const char *filename, GODotDot dotdot,
+go_filename_simplify (char const *filename, GODotDot dotdot,
gboolean make_absolute)
{
char *simp, *p, *q;
@@ -197,7 +197,7 @@
* Simplify a potentially non-local path using only slashes.
*/
static char *
-simplify_path (const char *uri)
+simplify_path (char const *uri)
{
char *simp, *p, *q;
@@ -234,9 +234,9 @@
}
static char *
-simplify_host_path (const char *uri, size_t hstart)
+simplify_host_path (char const *uri, size_t hstart)
{
- const char *slash = strchr (uri + hstart, '/');
+ char const *slash = strchr (uri + hstart, '/');
char *simp, *psimp;
size_t pstart;
@@ -253,7 +253,7 @@
}
char *
-go_url_simplify (const char *uri)
+go_url_simplify (char const *uri)
{
char *simp, *p;
@@ -287,7 +287,7 @@
* More or less the same as gnome_vfs_uri_make_full_from_relative.
*/
char *
-go_url_resolve_relative (const char *ref_uri, const char *rel_uri)
+go_url_resolve_relative (char const *ref_uri, char const *rel_uri)
{
char *simp, *uri;
@@ -323,10 +323,10 @@
/* ------------------------------------------------------------------------- */
static char *
-make_rel (const char *uri, const char *ref_uri,
- const char *uri_host, const char *slash)
+make_rel (char const *uri, char const *ref_uri,
+ char const *uri_host, char const *slash)
{
- const char *p, *q;
+ char const *p, *q;
int n;
GString *res;
@@ -364,7 +364,7 @@
}
char *
-go_url_make_relative (const char *uri, const char *ref_uri)
+go_url_make_relative (char const *uri, char const *ref_uri)
{
int i;
@@ -404,7 +404,7 @@
/* ------------------------------------------------------------------------- */
static gboolean
-is_fd_uri (const char *uri, int *fd)
+is_fd_uri (char const *uri, int *fd)
{
unsigned long ul;
char *end;
@@ -430,7 +430,7 @@
* encoding) to an escaped URI.
*/
char *
-go_shell_arg_to_uri (const char *arg)
+go_shell_arg_to_uri (char const *arg)
{
gchar *tmp;
int fd;
@@ -472,13 +472,13 @@
/**
* go_basename_from_uri:
- * @uri :
+ * @uri : The uri
*
* Decode the final path component. Returns as UTF-8 encoded suitable
* for display.
**/
char *
-go_basename_from_uri (const char *uri)
+go_basename_from_uri (char const *uri)
{
char *res;
@@ -504,14 +504,14 @@
/**
* go_dirname_from_uri:
- * @uri :
+ * @uri : target
* @brief: if TRUE, hide "file://" if present.
*
* Decode the all but the final path component. Returns as UTF-8 encoded
* suitable for display.
**/
char *
-go_dirname_from_uri (const char *uri, gboolean brief)
+go_dirname_from_uri (char const *uri, gboolean brief)
{
char *dirname_utf8, *dirname;
@@ -541,7 +541,7 @@
/* ------------------------------------------------------------------------- */
static GsfInput *
-open_plain_file (const char *path, GError **err)
+open_plain_file (char const *path, GError **err)
{
GsfInput *input = gsf_input_mmap_new (path, NULL);
if (input != NULL)
@@ -553,10 +553,11 @@
/**
* go_file_open :
- * @uri :
+ * @uri : target uri
* @err : #GError
*
* Try all available methods to open a file or return an error
+ * Returns: non-%NULL on success
**/
GsfInput *
go_file_open (char const *uri, GError **err)
@@ -639,10 +640,10 @@
/* Adapted from gtkfilechooserdefault.c. Unfortunately it is static there. */
GSList *
-go_file_split_urls (const char *data)
+go_file_split_urls (char const *data)
{
GSList *uris;
- const char *p, *q;
+ char const *p, *q;
uris = NULL;
@@ -697,7 +698,7 @@
gboolean islocal = FALSE;
#ifdef HAVE_PWD_H
struct passwd *password_info;
- const char *name;
+ char const *name;
gsize namelen;
char *nameutf8;
#endif
@@ -778,7 +779,7 @@
gboolean islocal = FALSE;
#ifdef HAVE_GRP_H
struct group *group_info;
- const char *name;
+ char const *name;
char *nameutf8;
#endif
@@ -1112,8 +1113,8 @@
gchar*
go_url_encode (gchar const *text, int type)
{
- const char *good;
- static const char hex[16] = "0123456789ABCDEF";
+ char const *good;
+ static char const hex[16] = "0123456789ABCDEF";
GString* result;
g_return_val_if_fail (text != NULL, NULL);
Modified: trunk/goffice/utils/go-font.c
==============================================================================
--- trunk/goffice/utils/go-font.c (original)
+++ trunk/goffice/utils/go-font.c Sun Jun 22 12:30:08 2008
@@ -47,7 +47,8 @@
* go_font_new_by_desc:
* @desc : #PangoFontDescription
*
- * Aborbs @desc and returns a ref to a font that matches it.
+ * NOTE : Absorbs @desc.
+ * Returns: a ref to a font that matches @desc.
**/
GOFont const *
go_font_new_by_desc (PangoFontDescription *desc)
Modified: trunk/goffice/utils/go-format.c
==============================================================================
--- trunk/goffice/utils/go-format.c (original)
+++ trunk/goffice/utils/go-format.c Sun Jun 22 12:30:08 2008
@@ -3836,11 +3836,10 @@
#ifdef DEFINE_COMMON
/**
* go_format_new_from_XL :
+ * @str: XL descriptor in UTF-8 encoding.
*
- * Looks up and potentially creates a GOFormat from the supplied string in
- * XL format.
- *
- * @descriptor_string: XL descriptor in UTF-8 encoding.
+ * Returns: Looks up and potentially creates a GOFormat from the supplied
+ * string in XL format.
**/
GOFormat *
go_format_new_from_XL (char const *str)
@@ -3885,11 +3884,13 @@
/**
* go_format_new_markup :
* @markup : #PangoAttrList
- * @add_ref :
+ * @add_ref : boolean
*
- * Create a MARKUP format. If @add_ref is FALSE absorb the reference to
- * @markup, otherwise add a reference.
- */
+ * If @add_ref is FALSE absorb the reference to @markup, otherwise add a
+ * reference.
+ *
+ * Returns: A new format.
+ **/
GOFormat *
go_format_new_markup (PangoAttrList *markup, gboolean add_ref)
{
@@ -3944,6 +3945,7 @@
*
* Adds a reference to a GOFormat.
*
+ * Returns: @gf
**/
GOFormat *
go_format_ref (GOFormat *gf)
Modified: trunk/goffice/utils/go-geometry.c
==============================================================================
--- trunk/goffice/utils/go-geometry.c (original)
+++ trunk/goffice/utils/go-geometry.c Sun Jun 22 12:30:08 2008
@@ -52,8 +52,7 @@
* @w: extent of segment
* @h: extent of segment
*
- * Computes the distance between a point and a segment.
- *
+ * Returns: the distance between a point and a segment.
**/
double
go_geometry_point_to_segment (double xp, double yp, double xs, double ys, double w, double h)
Modified: trunk/goffice/utils/go-glib-extras.c
==============================================================================
--- trunk/goffice/utils/go-glib-extras.c (original)
+++ trunk/goffice/utils/go-glib-extras.c Sun Jun 22 12:30:08 2008
@@ -97,11 +97,12 @@
/**
* go_slist_create:
- * @item1: First item.
+ * @item1: itionally %NULL
+ * @Varargs : %NULL terminated list of additional items
*
* Creates a GList from NULL-terminated list of arguments.
*
- * Return value: created list.
+ * Returns: created list.
**/
GSList *
go_slist_create (gpointer item1, ...)
@@ -730,8 +731,8 @@
/**
* go_get_real_name :
*
- * Return a utf8 encoded string with the current user name.
- * Caller should _NOT_ free the result.
+ * Returns: a utf8 encoded string with the current user name.
+ * Caller should _NOT_ free the result.
**/
char const *
go_get_real_name (void)
@@ -756,6 +757,7 @@
/**
* go_destroy_password :
+ * @passwd : The buffer to clear
*
* Overwrite a string holding a password. This is a separate routine to
* ensure that the compiler does not try to outsmart us.
@@ -771,7 +773,8 @@
/**
* go_object_toggle: toggle a boolean object property.
- *
+ * @object : #GObject
+ * @property_name : name
**/
void
go_object_toggle (gpointer object, const gchar *property_name)
Modified: trunk/goffice/utils/go-libxml-extras.c
==============================================================================
--- trunk/goffice/utils/go-libxml-extras.c (original)
+++ trunk/goffice/utils/go-libxml-extras.c Sun Jun 22 12:30:08 2008
@@ -23,13 +23,15 @@
/**
* go_xml_parse_file :
- * @filename:
+ * @filename: the locale path to a file to parse.
*
* Like xmlParseFile, but faster. Does not accept compressed files.
* See http://bugzilla.gnome.org/show_bug.cgi?id=168414
*
* Note: this reads the entire file into memory and should therefore
* not be used for user-supplied files.
+ *
+ * Returns: A libxml2 xmlDocPtr or %NULL.
**/
xmlDocPtr
go_xml_parse_file (char const *filename)
Modified: trunk/goffice/utils/go-locale.c
==============================================================================
--- trunk/goffice/utils/go-locale.c (original)
+++ trunk/goffice/utils/go-locale.c Sun Jun 22 12:30:08 2008
@@ -158,7 +158,9 @@
*
* Play with the default logic so that things come out nicely for the default
* case.
- */
+ *
+ * Returns: A string with the default currency
+ **/
GString const *
go_locale_get_currency (gboolean *precedes, gboolean *space_sep)
{
Modified: trunk/goffice/utils/go-pattern.c
==============================================================================
--- trunk/goffice/utils/go-pattern.c (original)
+++ trunk/goffice/utils/go-pattern.c Sun Jun 22 12:30:08 2008
@@ -203,10 +203,9 @@
* @pattern: a #GOPattern
* @cr: a cairo context
*
- * Creates a cairo pattern object corresponding to @pattern parameters. The returned
- * surface must be freed after use, using cairo_pattern_destroy.
+ * Returns: a cairo pattern object corresponding to @pattern parameters. The returned
+ * surface must be freed after use, using cairo_pattern_destroy.
**/
-
cairo_pattern_t *
go_pattern_create_cairo_pattern (GOPattern const *pattern, cairo_t *cr)
{
Modified: trunk/goffice/utils/go-undo.c
==============================================================================
--- trunk/goffice/utils/go-undo.c (original)
+++ trunk/goffice/utils/go-undo.c Sun Jun 22 12:30:08 2008
@@ -41,11 +41,12 @@
* @a: optional first undo operation
* @b: optional last undo operation
*
- * Combines two undo operations and returns the combination. This function
- * takes ownership of the argument references and gives ownership of the
- * result to the caller. Either argument may be NULL in which case the
+ * This function takes ownership of the argument references and gives ownership
+ * of the result to the caller. Either argument may be NULL in which case the
* other is returned.
- */
+ *
+ * Returns: the combination of two undo operations.
+ **/
GOUndo *
go_undo_combine (GOUndo *a, GOUndo *b)
{
Modified: trunk/goffice/utils/regutf8.c
==============================================================================
--- trunk/goffice/utils/regutf8.c (original)
+++ trunk/goffice/utils/regutf8.c Sun Jun 22 12:30:08 2008
@@ -343,10 +343,8 @@
* @repl: Check replacement part too.
* @err: Location to store error message.
*
- * Checks that validity of the search-and-replace data and returns TRUE
- * on success.
+ * Returns: %TRUE if search-and-replace data is valid.
**/
-
gboolean
go_search_replace_verify (GoSearchReplace *sr, gboolean repl, GError **err)
{
[
Date Prev][
Date Next] [
Thread Prev][
Thread Next]
[
Thread Index]
[
Date Index]
[
Author Index]
