Revision: 3531 http://geany.svn.sourceforge.net/geany/?rev=3531&view=rev Author: eht16 Date: 2009-01-30 18:53:23 +0000 (Fri, 30 Jan 2009)
Log Message: ----------- Add some missing @since tags to the API documentation of various functions.
Modified Paths: -------------- trunk/ChangeLog trunk/doc/plugins.dox trunk/src/dialogs.c trunk/src/document.c trunk/src/editor.c trunk/src/editor.h trunk/src/filetypes.c trunk/src/msgwindow.c trunk/src/sciwrappers.c trunk/src/ui_utils.c trunk/src/ui_utils.h trunk/src/utils.c
Modified: trunk/ChangeLog =================================================================== --- trunk/ChangeLog 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/ChangeLog 2009-01-30 18:53:23 UTC (rev 3531) @@ -8,6 +8,11 @@ as tooltips. * HACKING, doc/plugins.dox: Add a few notes about basic plugin writing guidelines. + * doc/plugins.dox, src/dialogs.c, src/document.c, src/editor.c, + src/editor.h, src/filetypes.c, src/msgwindow.c, src/sciwrappers.c, + src/ui_utils.c, src/ui_utils.h, src/utils.c: + Add some missing @since tags to the API documentation of various + functions.
2009-01-29 Enrico Tröger <enrico(dot)troeger(at)uvena(dot)de>
Modified: trunk/doc/plugins.dox =================================================================== --- trunk/doc/plugins.dox 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/doc/plugins.dox 2009-01-30 18:53:23 UTC (rev 3531) @@ -245,6 +245,8 @@ * @param user_data user data. * @return @c TRUE to stop other handlers from being invoked for the event. * @c FALSE to propagate the event further. + * + * @since 0.16 * @endsignaldef * *
Modified: trunk/src/dialogs.c =================================================================== --- trunk/src/dialogs.c 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/src/dialogs.c 2009-01-30 18:53:23 UTC (rev 3531) @@ -928,6 +928,8 @@ * (see documentation for @a gtk_spin_button_new_with_range()). * * @return @a TRUE if a value was entered and the dialog closed with 'OK'. @a FALSE otherwise. + * + * @since 0.16 **/ gboolean dialogs_show_input_numeric(const gchar *title, const gchar *label_text, gdouble *value, gdouble min, gdouble max, gdouble step)
Modified: trunk/src/document.c =================================================================== --- trunk/src/document.c 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/src/document.c 2009-01-30 18:53:23 UTC (rev 3531) @@ -124,6 +124,8 @@ * @return The matching document, or NULL. * @note This is only really useful when passing a @c TMWorkObject::file_name. * @see document_find_by_filename(). + * + * @since 0.15 **/ GeanyDocument* document_find_by_real_path(const gchar *realname) { @@ -596,6 +598,8 @@ * @param doc The document to remove. * * @return @a TRUE if the document was actually removed or @a FALSE otherwise. + * + * @since 0.15 **/ gboolean document_close(GeanyDocument *doc) { @@ -1501,7 +1505,9 @@ * * @param doc The current document which should be renamed. * @param new_filename The new filename in UTF-8 encoding. - */ + * + * @since 0.16 + **/ void document_rename_file(GeanyDocument *doc, const gchar *new_filename) { gchar *old_locale_filename = utils_get_locale_from_utf8(doc->file_name); @@ -1526,7 +1532,9 @@ * @return @c TRUE if the file was saved or @c FALSE if the file could not be saved. * * @see document_save_file(). - */ + * + * @since 0.16 + **/ gboolean document_save_file_as(GeanyDocument *doc, const gchar *utf8_fname) { gboolean ret; @@ -2698,7 +2706,10 @@ /** Accessor function for @ref GeanyData::documents_array items. * @warning Always check the returned document is valid (@c doc->is_valid). * @param idx @c documents_array index. - * @return The document, or @c NULL if @a idx is out of range. */ + * @return The document, or @c NULL if @a idx is out of range. + * + * @since 0.16 + */ GeanyDocument *document_index(gint idx) { return (idx >= 0 && idx < (gint) documents_array->len) ? documents[idx] : NULL;
Modified: trunk/src/editor.c =================================================================== --- trunk/src/editor.c 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/src/editor.c 2009-01-30 18:53:23 UTC (rev 3531) @@ -3692,7 +3692,9 @@ * * @param editor The editor to operate on. * @param indic The indicator number to clear, this is a value of @ref GeanyIndicator. - **/ + * + * @since 0.16 + */ void editor_indicator_clear(GeanyEditor *editor, gint indic) { glong last_pos; @@ -3715,7 +3717,9 @@ * @param editor The editor to operate on. * @param indic The indicator number to use, this is a value of @ref GeanyIndicator. * @param line The line number which should be marked. - **/ + * + * @since 0.16 + */ void editor_indicator_set_on_line(GeanyEditor *editor, gint indic, gint line) { gint start, end; @@ -3758,7 +3762,9 @@ * @param indic The indicator number to use, this is a value of @ref GeanyIndicator. * @param start The starting position for the marker. * @param end The ending position for the marker. - **/ + * + * @since 0.16 + */ void editor_indicator_set_on_range(GeanyEditor *editor, gint indic, gint start, gint end) { if (editor == NULL || start >= end) @@ -4067,7 +4073,10 @@
/** Set the indent type for @a editor. * @param editor Editor. - * @param type Indent type. */ + * @param type Indent type. + * + * @since 0.16 + */ void editor_set_indent_type(GeanyEditor *editor, GeanyIndentType type) { const GeanyIndentPrefs *iprefs = editor_get_indent_prefs(editor); @@ -4255,7 +4264,10 @@
/** Create a new Scintilla @c GtkWidget based on the settings for @a editor. * @param editor Editor settings. - * @return The new widget. */ + * @return The new widget. + * + * @since 0.15 + **/ ScintillaObject *editor_create_widget(GeanyEditor *editor) { const GeanyIndentPrefs *iprefs = get_default_indent_prefs();
Modified: trunk/src/editor.h =================================================================== --- trunk/src/editor.h 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/src/editor.h 2009-01-30 18:53:23 UTC (rev 3531) @@ -74,7 +74,10 @@ GeanyIndicator;
/** Indentation prefs that might be different according to project or filetype. - * Use @c editor_get_indent_prefs() to lookup the prefs for a particular document. */ + * Use @c editor_get_indent_prefs() to lookup the prefs for a particular document. + * + * @since 0.15 + **/ typedef struct GeanyIndentPrefs { gint width; /**< Indent width. */
Modified: trunk/src/filetypes.c =================================================================== --- trunk/src/filetypes.c 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/src/filetypes.c 2009-01-30 18:53:23 UTC (rev 3531) @@ -1316,7 +1316,10 @@
/** Find a filetype pointer from its @c name field. * @param name Filetype name. - * @return The filetype found, or @c NULL. */ + * @return The filetype found, or @c NULL. + * + * @since 0.15 + **/ GeanyFiletype *filetypes_lookup_by_name(const gchar *name) { GeanyFiletype *ft; @@ -1456,7 +1459,10 @@ /** Accessor function for @ref GeanyData::filetypes_array items. * Example: @code ft = filetypes_index(GEANY_FILETYPES_C); @endcode * @param idx @c filetypes_array index. - * @return The filetype, or @c NULL if @a idx is out of range. */ + * @return The filetype, or @c NULL if @a idx is out of range. + * + * @since 0.16 + */ GeanyFiletype *filetypes_index(gint idx) { return (idx >= 0 && idx < (gint) filetypes_array->len) ? filetypes[idx] : NULL;
Modified: trunk/src/msgwindow.c =================================================================== --- trunk/src/msgwindow.c 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/src/msgwindow.c 2009-01-30 18:53:23 UTC (rev 3531) @@ -273,6 +273,8 @@ * @param doc The document. Set to @c NULL to ignore. * @param format @c printf()-style format string. * @param ... Arguments for the @c format string. + * + * @since 0.15 **/ void msgwin_msg_add(gint msg_color, gint line, GeanyDocument *doc, const gchar *format, ...) { @@ -1006,6 +1008,8 @@ * @param tabnum An index of a tab in the messages window. Valid values are all elements of * #MessageWindowTabNum. * @param show Whether to show the messages window at all if it was hidden before. + * + * @since 0.15 **/ void msgwin_switch_tab(gint tabnum, gboolean show) { @@ -1034,6 +1038,8 @@ * * @param tabnum An index of a tab in the messages window which should be cleared. * Valid values are @a MSG_STATUS, @a MSG_COMPILER and @a MSG_MESSAGE. + * + * @since 0.15 **/ void msgwin_clear_tab(gint tabnum) {
Modified: trunk/src/sciwrappers.c =================================================================== --- trunk/src/sciwrappers.c 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/src/sciwrappers.c 2009-01-30 18:53:23 UTC (rev 3531) @@ -684,7 +684,10 @@
/** Get display tab width (this is not indent width, see GeanyIndentPrefs). * @param sci Scintilla widget. - * @return Width. */ + * @return Width. + * + * @since 0.15 + **/ gint sci_get_tab_width(ScintillaObject * sci) { return SSM(sci, SCI_GETTABWIDTH, 0, 0); @@ -720,7 +723,10 @@
/** Check if there's a selection. * @param sci Scintilla widget. - * @return Whether a selection is present. */ + * @return Whether a selection is present. + * + * @since 0.15 + **/ gboolean sci_has_selection(ScintillaObject *sci) { if (SSM(sci, SCI_GETSELECTIONEND,0,0) - SSM(sci, SCI_GETSELECTIONSTART,0,0)) @@ -926,7 +932,10 @@ /** A simple convenience function for sending Scintilla commands without any parameters. * @param sci The Scintilla @c GtkWidget. * @param cmd @c SCI_COMMAND. - * @see http://scintilla.org for the documentation. */ + * @see http://scintilla.org for the documentation. + * + * @since 0.16 + */ void sci_send_command(ScintillaObject * sci, gint cmd) { SSM(sci, cmd, 0, 0); @@ -986,7 +995,9 @@ * @param indic The indicator number to set. * * @see sci_indicator_clear - **/ + * + * @since 0.16 + */ void sci_indicator_set(ScintillaObject *sci, gint indic) { SSM(sci, SCI_SETINDICATORCURRENT, indic, 0); @@ -1006,7 +1017,9 @@ * @param sci Scintilla widget. * @param pos Starting position. * @param len Length. - **/ + * + * @since 0.16 + */ void sci_indicator_clear(ScintillaObject *sci, gint pos, gint len) { SSM(sci, SCI_INDICATORCLEARRANGE, pos, len); @@ -1030,7 +1043,10 @@ /** Find a matching brace at @a pos. * @param sci Scintilla widget. * @param pos Position. - * @return Matching brace position. */ + * @return Matching brace position. + * + * @since 0.15 + **/ gint sci_find_matching_brace(ScintillaObject *sci, gint pos) { return SSM(sci, SCI_BRACEMATCH, pos, 0);
Modified: trunk/src/ui_utils.c =================================================================== --- trunk/src/ui_utils.c 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/src/ui_utils.c 2009-01-30 18:53:23 UTC (rev 3531) @@ -690,7 +690,10 @@ /** Add a widget to the list of widgets that should be set sensitive/insensitive * when some documents are present/no documents are open. * It will be removed when the widget is destroyed. - * @param widget The widget to add. */ + * @param widget The widget to add. + * + * @since 0.15 + **/ void ui_add_document_sensitive(GtkWidget *widget) { gboolean enable = gtk_notebook_get_n_pages(GTK_NOTEBOOK(main_widgets.notebook)) ? TRUE : FALSE; @@ -1170,7 +1173,10 @@ /** Create a @c GtkImageMenuItem with a stock image and a custom label. * @param stock_id Stock image ID, e.g. @c GTK_STOCK_OPEN. * @param label Menu item label, can include mnemonics. - * @return The new @c GtkImageMenuItem. */ + * @return The new @c GtkImageMenuItem. + * + * @since 0.16 + */ GtkWidget * ui_image_menu_item_new(const gchar *stock_id, const gchar *label) { @@ -1200,6 +1206,8 @@ * nothing happens. If ran with GTK 2.16 or newer, the icon is displayed. * * @param entry The GtkEntry object to which the icon should be attached. + * + * @since 0.16 */ void ui_entry_add_clear_icon(GtkWidget *entry) { @@ -1753,6 +1761,8 @@ * * @param widget The widget the tooltip should be set for. * @param text The text for the tooltip. + * + * @since 0.16 */ void ui_widget_set_tooltip_text(GtkWidget *widget, const gchar *text) { @@ -1776,7 +1786,10 @@ * @param widget Widget with the @a widget_name property set. * @param widget_name Name to lookup. * @return The widget found. - * @see ui_hookup_widget(). */ + * @see ui_hookup_widget(). + * + * @since 0.16 + */ GtkWidget *ui_lookup_widget(GtkWidget *widget, const gchar *widget_name) { GtkWidget *parent, *found_widget; @@ -1841,7 +1854,9 @@ * in @c src/printing.c. * * @param text The text to be shown as the progress bar label or NULL to leave it empty. - */ + * + * @since 0.16 + **/ void ui_progress_bar_start(const gchar *text) { g_return_if_fail(progress_bar_timer_id == (guint) -1); @@ -1857,7 +1872,10 @@ }
-/** Stops a running progress bar and hides the widget again. */ +/** Stops a running progress bar and hides the widget again. + * + * @since 0.16 + **/ void ui_progress_bar_stop(void) { gtk_widget_hide(GTK_WIDGET(main_widgets.progressbar));
Modified: trunk/src/ui_utils.h =================================================================== --- trunk/src/ui_utils.h 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/src/ui_utils.h 2009-01-30 18:53:23 UTC (rev 3531) @@ -28,7 +28,10 @@ * @param owner Usually a @c GtkWindow. * @param widget Widget. * @param widget_name Name. - * @see ui_lookup_widget(). */ + * @see ui_lookup_widget(). + * + * @since 0.16 + **/ #define ui_hookup_widget(owner, widget, widget_name) \ g_object_set_data_full(G_OBJECT(owner), widget_name, \ g_object_ref(widget), (GDestroyNotify)g_object_unref);
Modified: trunk/src/utils.c =================================================================== --- trunk/src/utils.c 2009-01-30 18:10:27 UTC (rev 3530) +++ trunk/src/utils.c 2009-01-30 18:53:23 UTC (rev 3531) @@ -67,6 +67,8 @@ * browsers. * * @param uri The URI to open in the web browser. + * + * @since 0.16 **/ void utils_open_browser(const gchar *uri) { @@ -342,7 +344,9 @@ * * @return an integer less than, equal to, or greater than zero if @a s1 is found, respectively, * to be less than, to match, or to be greater than @a s2. - **/ + * + * @since 0.16 + */ gint utils_str_casecmp(const gchar *s1, const gchar *s2) { gchar *tmp1, *tmp2; @@ -566,7 +570,9 @@ * @param time_to_use The date/time to use, in time_t format or NULL to use the current time. * * @return A newly-allocated string, should be freed when no longer needed. - **/ + * + * @since 0.16 + */ gchar *utils_get_date_time(const gchar *format, time_t *time_to_use) { const struct tm *tm; @@ -1334,7 +1340,8 @@
/** - * Convenience function to replace only the occurrence of @c needle in @c haystack with @c. + * Convenience function to replace only the first occurrence of @c needle in @c haystack + * with @ replace. * For details, see utils_string_replace_all(). * * @param haystack The input string to operate on. This string is modified in place. @@ -1342,6 +1349,8 @@ * @param replace The replacement for @c needle. * * @return @a amount of replacements done + * + * @since 0.16 */ guint utils_string_replace_first(GString *haystack, const gchar *needle, const gchar *replace) {
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.