SF.net SVN: geany:[3531] trunk
eht16 at users.sourceforge.net
eht16 at xxxxx
Fri Jan 30 18:53:23 UTC 2009
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.
More information about the Commits
mailing list