Commit e3218c53 authored by David Hoover's avatar David Hoover Committed by Morten Welinder

mass addition of new gtk-doc-style comments for functions, some cleanup of

2004-09-23  David Hoover <karma@deadmoose.com>
	* src/*.c: mass addition of new gtk-doc-style comments for functions,
	some cleanup of language & formatting in existing comments, minor
	whitespace fixes, etc.

	Slightly revised and committed by terra@gnome.org (Morten Welinder)
parent fe825b06
2004-09-23 David Hoover <karma@deadmoose.com>
* src/*.c: mass addition of new gtk-doc-style comments for functions,
some cleanup of language & formatting in existing comments, minor
whitespace fixes, etc.
Slightly revised and committed by terra@gnome.org (Morten Welinder)
2004-07-26 Shane Butler <shane_b@users.sourceforge.net>
* widgets/gtkbox.xml: Fixed bug with loading GtkBoxes where too
......
......@@ -54,7 +54,7 @@ if (...) {
Over time we'll migrate to the preferred form.
Naming conventions:
- function names sholud be lowercase and prefixed with the
- function names should be lowercase and prefixed with the
file name (or, if the function is static and the name too long,
with an abbreviation), e.g:
glade_project_window_my_function ()
......
......@@ -63,7 +63,7 @@ Normal tasks:
B__ C
|
\__ D
When hiding the childs of "A" and showingt htem again, the state of B and its
When hiding the childs of "A" and showing them again, the state of B and its
childs is lost, this should go into gtk+.
......@@ -84,7 +84,7 @@ Problems found with the gtk-spin button
- Does not emit a click up, click down signal
- If you change the max or min of the adjustment and emit an adjustment
changed signal it does not evaluates if the current value is inside the range
- The inability to be used wihtout an adjustment (clock)
- The inability to be used without an adjustment (clock)
discuss with jamesh
- How are we going to save pixmaps
......
......@@ -37,7 +37,12 @@
#define GLADE_TAG_PALETTE "GladePalette"
/**
* glade_catalog_delete:
* @catalog:
*
* Frees @catalog and its associated memory.
*/
void
glade_catalog_delete (GladeCatalog *catalog)
{
......@@ -158,6 +163,13 @@ lblError:
return NULL;
}
/**
* glade_catalog_load_all:
*
* TODO: write me
*
* Returns:
*/
GList *
glade_catalog_load_all (void)
{
......@@ -202,15 +214,28 @@ glade_catalog_load_all (void)
return catalogs;
}
const char *glade_catalog_get_title (GladeCatalog *catalog)
/**
* glade_catalog_get_title:
* @catalog: a #GladeCatalog
*
* Returns: a pointer to the title of @catalog
*/
const char *
glade_catalog_get_title (GladeCatalog *catalog)
{
g_return_val_if_fail (catalog != NULL, NULL);
return catalog->title;
}
GList *glade_catalog_get_widget_classes (GladeCatalog *catalog)
/**
* glade_catalog_get_widget_classes:
* @catalog: a #GladeCatalog
*
* Returns: a #GList containing the widget classes in @catalog
*/
GList *
glade_catalog_get_widget_classes (GladeCatalog *catalog)
{
g_return_val_if_fail (catalog != NULL, NULL);
return catalog->widget_classes;
}
......@@ -26,6 +26,11 @@
#include "glade-xml-utils.h"
#include "glade-choice.h"
/**
* glade_choice_new:
*
* Returns: a new #GladeChoice
*/
GladeChoice *
glade_choice_new (void)
{
......@@ -36,6 +41,12 @@ glade_choice_new (void)
return choice;
}
/**
* glade_choice_clone:
* @choice: a #GladeChoice
*
* Returns: a new #GladeChoice cloned from @choice
*/
GladeChoice *
glade_choice_clone (GladeChoice *choice)
{
......@@ -50,6 +61,12 @@ glade_choice_clone (GladeChoice *choice)
return clone;
}
/**
* glade_choice_free:
* @choice: a #GladeChoice
*
* Frees @choice and its associated memory.
*/
void
glade_choice_free (GladeChoice *choice)
{
......@@ -159,6 +176,14 @@ glade_choice_new_from_value (GEnumValue value)
return choice;
}
/**
* glade_choice_list_new_from_spec:
* @spec: a #GParamSpec
*
* TODO: write me
*
* Returns:
*/
GList *
glade_choice_list_new_from_spec (GParamSpec *spec)
{
......@@ -213,6 +238,14 @@ glade_choice_new_from_node (GladeXmlNode *node)
return choice;
}
/**
* glade_choice_list_new_from_node:
* @node: a #GladeXmlNode
*
* TODO: write me
*
* Returns:
*/
GList *
glade_choice_list_new_from_node (GladeXmlNode *node)
{
......
......@@ -34,21 +34,23 @@ struct _GladeChoice {
*/
gchar *id;
#if 0
gchar *symbol; /* Symbol for the choice. Like GTK_WINDOW_TOPLEVEL (which
* is an integer) or GNOME_STOCK_BUTTON_FOO (which is
* not an integer). For integers which are enum'ed values
* this symbol is converted to its value
gchar *symbol; /* Symbol for the choice. Like GTK_WINDOW_TOPLEVEL
* (which is an integer) or GNOME_STOCK_BUTTON_FOO
* (which is not an integer). For integers which are
* enum'ed values this symbol is converted to its
* value
*/
#endif
gint value; /* The enum value of the symbol. The symbol GTK_WINDOW_
* TOPLEVEL will be 0 and GTK_WINDOW_POPUP will be 1
gint value; /* The enum value of the symbol. The symbol
* GTK_WINDOW_TOPLEVEL will be 0 and GTK_WINDOW_POPUP
* will be 1
*/
#if 0
const gchar *string; /* For non-integer values like GNOME_STOCK_BUTTON_OK
* it points to a string inside the library that
* contains it.
const gchar *string; /* For non-integer values like
* GNOME_STOCK_BUTTON_OK it points to a string
* inside the library that contains it.
* See glade-choice.c#glade_string_from_sring
*/
#endif
......
......@@ -43,6 +43,13 @@ glade_clipboard_view_init (GladeClipboardView *view)
view->model = NULL;
}
/**
* glade_clipboard_view_get_type:
*
* Creates the typecode for the #GladeClipboardView object type.
*
* Returns: the typecode for the #GladeClipboardView object type
*/
GType
glade_clipboard_view_get_type ()
{
......@@ -192,12 +199,12 @@ glade_clipboard_view_construct (GladeClipboardView *view)
/**
* glade_clipboard_view_new:
* @clipboard
* @clipboard: a #GladeClipboard
*
* Create a new #GladeClipboardView widget.
* Create a new #GladeClipboardView widget for @clipboard.
*
* Return Value: a #GtkWidget.
**/
* Returns: a new #GladeClipboardView cast to be a #GtkWidget
*/
GtkWidget *
glade_clipboard_view_new (GladeClipboard *clipboard)
{
......@@ -212,6 +219,13 @@ glade_clipboard_view_new (GladeClipboard *clipboard)
return GTK_WIDGET (view);
}
/**
* glade_clipboard_view_add:
* @view: a #GladeClipboardView
* @widget: a #GladeWidget
*
* Adds @widget to @view.
*/
void
glade_clipboard_view_add (GladeClipboardView *view, GladeWidget *widget)
{
......@@ -224,6 +238,13 @@ glade_clipboard_view_add (GladeClipboardView *view, GladeWidget *widget)
gtk_list_store_set (view->model, &iter, 0, widget, -1);
}
/**
* glade_cliboard_view_remove:
* @view: a #GladeClipboardView
* @widget: a #GladeWidget
*
* Removes @widget from @view.
*/
void
glade_clipboard_view_remove (GladeClipboardView *view, GladeWidget *widget)
{
......@@ -245,4 +266,3 @@ glade_clipboard_view_remove (GladeClipboardView *view, GladeWidget *widget)
gtk_list_store_remove (view->model, &iter);
}
......@@ -47,10 +47,10 @@ glade_clipboard_init (GladeClipboard *clipboard)
/**
* glade_clipboard_get_type:
*
* Creates the typecode for the GladeClipboard object type.
* Creates the typecode for the #GladeClipboard object type.
*
* Return value: the typecode for the GladeClipboard object type.
**/
* Returns: the typecode for the #GladeClipboard object type
*/
GType
glade_clipboard_get_type ()
{
......@@ -78,12 +78,9 @@ glade_clipboard_get_type ()
/**
* glade_clipboard_new:
* @:
*
* Create a new @GladeClipboard object.
*
* Return Value: a @GladeClipboard object.
**/
* Returns: a new #GladeClipboard object
*/
GladeClipboard *
glade_clipboard_new ()
{
......@@ -92,11 +89,12 @@ glade_clipboard_new ()
/**
* glade_clipboard_add:
* @clipboard:
* @widget:
* @clipboard: a #GladeClipboard
* @widget: a #GladeWidget
*
* Move a GladeWidget onto the Clipboard.
**/
* Adds @widget to @clipboard.
* This increses the reference count of @widget.
*/
void
glade_clipboard_add (GladeClipboard *clipboard, GladeWidget *widget)
{
......@@ -117,11 +115,11 @@ glade_clipboard_add (GladeClipboard *clipboard, GladeWidget *widget)
/**
* glade_clipboard_remove:
* @clipboard:
* @widget:
* @clipboard: a #GladeClipboard
* @widget: a #GladeWidget
*
* Remove a GladeWidget from the Clipboard
**/
* Removes a @widget from @clipboard.
*/
void
glade_clipboard_remove (GladeClipboard *clipboard, GladeWidget *widget)
{
......@@ -142,4 +140,3 @@ glade_clipboard_remove (GladeClipboard *clipboard, GladeWidget *widget)
if (clipboard->view)
glade_clipboard_view_remove (GLADE_CLIPBOARD_VIEW (clipboard->view), widget);
}
......@@ -143,6 +143,12 @@ static MAKE_TYPE(func, type, GLADE_TYPE_COMMAND)
/**************************************************/
/**
* glade_command_undo:
* @project: a #GladeProject
*
* Undoes the last command performed in @project.
*/
void
glade_command_undo (GladeProject *project)
{
......@@ -168,6 +174,12 @@ glade_command_undo (GladeProject *project)
project->prev_redo_item = prev_redo_item->prev;
}
/**
* glade_command_redo:
* @project: a #GladeProject
*
* Redoes the last undone command in @project.
*/
void
glade_command_redo (GladeProject *project)
{
......@@ -285,8 +297,8 @@ glade_command_set_property_undo (GladeCommand *cmd)
}
/**
* Execute the set property command and revert it. Ie, after the execution of this
* function cmd will point to the undo action
* Execute the set property command and revert it. IE, after the execution of
* this function cmd will point to the undo action
*/
static gboolean
glade_command_set_property_execute (GladeCommand *cmd)
......@@ -677,6 +689,12 @@ glade_command_create_delete_common (GladeWidget *widget,
glade_command_push_undo (widget->project, GLADE_COMMAND (me));
}
/**
* glade_command_delete:
* @widget: a #GladeWidget
*
* TODO: write me
*/
void
glade_command_delete (GladeWidget *widget)
{
......@@ -695,6 +713,14 @@ glade_command_delete (GladeWidget *widget)
* the new widget will be assigned to (if NULL, the project will be extracted
* from the placeholder).
*/
/**
* glade_command_create:
* @class:
* @placeholder:
* @project:
*
* TODO: write me
*/
void
glade_command_create (GladeWidgetClass *class,
GladePlaceholder *placeholder,
......@@ -929,6 +955,12 @@ glade_command_paste (GladePlaceholder *placeholder)
glade_command_cut_paste_common (widget, placeholder, parent->project, FALSE);
}
/**
* glade_command_cut:
* @widget: a #GladeWidget
*
* TODO: write me
*/
void
glade_command_cut (GladeWidget *widget)
{
......@@ -1014,7 +1046,7 @@ glade_command_add_signal_collapse (GladeCommand *this, GladeCommand *other)
}
static void
glade_command_add_remove_signal(GladeWidget *glade_widget, const GladeSignal *signal, gboolean add)
glade_command_add_remove_signal (GladeWidget *glade_widget, const GladeSignal *signal, gboolean add)
{
GladeCommandAddSignal *me = GLADE_COMMAND_ADD_SIGNAL (g_object_new (GLADE_COMMAND_ADD_SIGNAL_TYPE, NULL));
GladeCommand *cmd = GLADE_COMMAND (me);
......@@ -1037,14 +1069,28 @@ glade_command_add_remove_signal(GladeWidget *glade_widget, const GladeSignal *si
glade_command_push_undo (glade_widget->project, cmd);
}
/**
* glade_command_add_signal:
* @glade_widget: a #GladeWidget
* @signal: a #GladeSignal
*
* TODO: write me
*/
void
glade_command_add_signal(GladeWidget *glade_widget, const GladeSignal *signal)
glade_command_add_signal (GladeWidget *glade_widget, const GladeSignal *signal)
{
glade_command_add_remove_signal (glade_widget, signal, TRUE);
}
/**
* glade_command_remove_signal:
* @glade_widget: a #GladeWidget
* @signal: a #GladeSignal
*
* TODO: write me
*/
void
glade_command_remove_signal(GladeWidget *glade_widget, const GladeSignal *signal)
glade_command_remove_signal (GladeWidget *glade_widget, const GladeSignal *signal)
{
glade_command_add_remove_signal (glade_widget, signal, FALSE);
}
......@@ -25,6 +25,13 @@
GladeCursor *cursor = NULL;
/**
* glade_cursor_set:
* @window: a #GdkWindow
* @type: a #GladeCursorType
*
* Sets the cursor for @window to something appropriate based on @type.
*/
void
glade_cursor_set (GdkWindow *window, GladeCursorType type)
{
......@@ -41,6 +48,11 @@ glade_cursor_set (GdkWindow *window, GladeCursorType type)
}
/**
* glade_cursor_init:
*
* Initializes cursors for use with glade_cursor_set().
*/
void
glade_cursor_init (void)
{
......
......@@ -38,7 +38,7 @@ glade_log_handler (const char *domain,
const char *message,
gpointer data)
{
static volatile int want_breakpoint = 1;
static volatile int want_breakpoint = 0;
g_log_default_handler (domain, level, message, data);
if (want_breakpoint && ((level & (G_LOG_LEVEL_CRITICAL /* | G_LOG_LEVEL_WARNING */)) != 0))
......@@ -51,6 +51,12 @@ glade_set_log_handler (const char *domain)
g_log_set_handler (domain, G_LOG_LEVEL_MASK, glade_log_handler, NULL);
}
/**
* glade_setup_log_handlers:
*
* Sets up a log handler to manage all %G_LOG_LEVEL_MASK errors of domain:
* GLib, GLib-GObject, Gtk, Gdk, and domainless.
*/
void
glade_setup_log_handlers ()
{
......
......@@ -109,6 +109,13 @@ glade_editor_marshal_VOID__STRING_ULONG_UINT_STRING (GClosure *closure,
data2);
}
/**
* glade_editor_get_type:
*
* Creates the typecode for the #GladeEditor object type.
*
* Returns: the typecode for the #GladeEditor object type
*/
GType
glade_editor_get_type (void)
{
......@@ -156,6 +163,15 @@ glade_editor_class_init (GladeEditorClass *class)
class->add_signal = NULL;
}
/**
* glade_editor_notebook_page:
* @name:
* @notebook:
*
* TODO: write me
*
* Returns:
*/
GtkWidget *
glade_editor_notebook_page (const gchar *name, GtkWidget *notebook)
{
......@@ -194,6 +210,11 @@ glade_editor_init (GladeEditor *editor)
editor->loading = FALSE;
}
/**
* glade_editor_new:
*
* Returns: a new #GladeEditor
*/
GladeEditor *
glade_editor_new ()
{
......@@ -231,7 +252,7 @@ glade_editor_widget_name_changed (GtkWidget *editable, GladeEditor *editor)
g_free (new_name);
}
/* ================================ Property Changed ==================================== */
/* ============================ Property Changed ============================ */
static void
glade_editor_property_changed_text_common (GladeProperty *property,
const gchar *text)
......@@ -642,7 +663,7 @@ glade_editor_property_show_flags_dialog (GtkWidget *entry,
gtk_widget_destroy (dialog);
}
/* ================================ Create inputs ==================================== */
/* ============================= Create inputs ============================= */
static GtkWidget *
glade_editor_create_input_enum_item (GladeEditorProperty *property,
GladeChoice *choice)
......@@ -864,6 +885,14 @@ glade_editor_create_input_object (GladeEditorProperty *property,
return NULL;
}
/**
* glade_editor_create_item_labe:
* @class:
*
* TODO: write me
*
* Returns:
*/
GtkWidget *
glade_editor_create_item_label (GladePropertyClass *class)
{
......@@ -1198,6 +1227,12 @@ glade_editor_load_common_page (GladeEditor *editor, GladeWidgetClass *class)
FALSE, TRUE, 0);
}
/**
* glade_editor_update_widget_name:
* @editor: a #GladeEditor
*
* TODO: write me
*/
void
glade_editor_update_widget_name (GladeEditor *editor)
{
......@@ -1229,7 +1264,7 @@ glade_editor_load_widget_class (GladeEditor *editor, GladeWidgetClass *class)
editor->loaded_class = class;
}
/* ================================ Load properties ================================== */
/* ============================ Load properties ============================ */
static void
glade_editor_property_set_tooltips (GladeEditorProperty *property)
{
......@@ -1632,11 +1667,11 @@ glade_editor_load_packing_page (GladeEditor *editor, GladeWidget *widget)
/**
* glade_editor_load_widget:
* @editor:
* @widget:
* @editor: a #GladeEditor
* @widget: a #GladeWidget
*
* Load @widget into the editor, if widget is NULL clear the editor.
**/
* Load @widget into @editor. If @widget is %NULL, clear the editor.
*/
void
glade_editor_load_widget (GladeEditor *editor, GladeWidget *widget)
{
......@@ -1690,6 +1725,14 @@ glade_editor_load_widget (GladeEditor *editor, GladeWidget *widget)
editor->loading = FALSE;
}
/**
* glade_editor_add_signal:
* @editor: a #GladeEditor
* @signal_id:
* @callback_name:
*
* TODO: write me
*/
void
glade_editor_add_signal (GladeEditor *editor,
guint signal_id,
......@@ -1711,4 +1754,3 @@ glade_editor_add_signal (GladeEditor *editor,
glade_editor_signals [ADD_SIGNAL], 0,
widget_name, widget_type, signal_id, callback_name);
}
......@@ -57,6 +57,13 @@
#define GLADEGTK_API
#endif
/**
* glade_gtk_option_menu_set_items:
* @object:
* @value:
*
* TODO: write me
*/
void GLADEGTK_API
glade_gtk_option_menu_set_items (GObject *object, GValue *value)
{
......@@ -95,6 +102,12 @@ glade_gtk_option_menu_set_items (GObject *object, GValue *value)
gtk_option_menu_set_menu (GTK_OPTION_MENU (option_menu), menu);
}
/**
* glade_gtk_widget_condition:
* @klass:
*
* TODO: write me
*/
int GLADEGTK_API
glade_gtk_widget_condition (GladeWidgetClass *klass)
{
......@@ -116,6 +129,13 @@ glade_gtk_widget_condition (GladeWidgetClass *klass)
}
}
/**
* glade_gtk-widget_set_tooltip:
* @object:
* @value:
*
* TODO: write me
*/
void GLADEGTK_API
glade_gtk_widget_set_tooltip (GObject *object, GValue *value)
{
......@@ -132,6 +152,13 @@ glade_gtk_widget_set_tooltip (GObject *object, GValue *value)
gtk_tooltips_set_tip (tooltips, GTK_WIDGET (object), NULL, NULL);
}
/**
* glade_gtk-widget_get_tooltip:
* @object:
* @value:
*
* TODO: write me
*/
void GLADEGTK_API
glade_gtk_widget_get_tooltip (GObject *object, GValue *value)
{
......@@ -141,6 +168,13 @@ glade_gtk_widget_get_tooltip (GObject *object, GValue *value)
g_value_set_string (value, tooltips_data->tip_text);
}
/**
* glade_gtk_progress_bar_set_format:
* @object:
* @value:
*
* TODO: write me
*/
void GLADEGTK_API
glade_gtk_progress_bar_set_format (GObject *object, GValue *value)
{
......@@ -153,6 +187,13 @@ glade_gtk_progress_bar_set_format (GObject *object, GValue *value)
gtk_progress_set_format_string (GTK_PROGRESS (bar), format);
}
/**
* glade_gtk_spin_button_set_max:
* @object:
* @value:
*
* TODO: write me
*/
void GLADEGTK_API
glade_gtk_spin_button_set_max (GObject *object, GValue *value)
{
......@@ -164,7 +205,13 @@ glade_gtk_spin_button_set_max (GObject *object, GValue *value)
gtk_adjustment_changed (adjustment);
}
/**
* glade_gtk_spin_button_set_min:
* @object:
* @value:
*
* TODO: write me
*/
void GLADEGTK_API
glade_gtk_spin_button_set_min (GObject *object, GValue *value)
{
......@@ -176,6 +223,13 @@ glade_gtk_spin_button_set_min (GObject *object, GValue *value)
gtk_adjustment_changed (adjustment);
}
/**
* glade_gtk_spin_button_set_step_increment:
* @object:
* @value:
*
* TODO: write me
*/
void GLADEGTK_API
glade_gtk_spin_button_set_step_increment (GObject *object, GValue *value)
{
......@@ -187,6 +241,13 @@ glade_gtk_spin_button_set_step_increment (GObject *object, GValue *value)
gtk_adjustment_changed (adjustment);
}
/**
* glade_gtk_spin_button_set_page_increment:
* @object:
* @value:
*
* TODO: write me
*/
void GLADEGTK_API
glade_gtk_spin_button_set_page_increment (GObject *object, GValue *value)
{
......@@ -198,6 +259,13 @@ glade_gtk_spin_button_set_page_increment (GObject *object, GValue *value)
gtk_adjustment_changed (adjustment);
}
/**
* glade_gtk_spin_button_set_page_size:
* @object:
* @value:
*
* TODO: write me
*/
void GLADEGTK_API
glade_gtk_spin_button_set_page_size (GObject *object, GValue *value)
{
......@@ -209,7 +277,13 @@ glade_gtk_spin_button_set_page_size (GObject *object, GValue *value)
gtk_adjustment_changed (adjustment);
}
/**
* glade_gtk_box_get_size:
* @object:
* @value:
*
* TODO: write me
*/
void GLADEGTK_API
glade_gtk_box_get_size (GObject *object, GValue *value)
{
......@@ -219,6 +293,13 @@ glade_gtk_box_get_size (GObject *object, GValue *value)
g_value_set_int (value, g_list_length (box->children));
}
/**
* glade_gtk_box_set_size:
* @object:
* @value:
*
* TODO: write me
*/