HybridDog/geany
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Add some missing @since tags to the API documentation of various functions.

Browse Source 
git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@3531 ea778897-0a13-0410-b9d1-a72fbfd435f5
This commit is contained in:
Enrico Tröger 2009-01-30 18:53:23 +00:00
parent 84fc7556eb
commit b2eeefc919
12 changed files with 119 additions and 26 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
ChangeLog
View File

@ -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>

2
doc/plugins.dox
View File

@ -245,6 +245,8 @@ PluginCallback plugin_callbacks[] =
* @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
*
*

2
src/dialogs.c
View File

@ -928,6 +928,8 @@ dialogs_show_input(const gchar *title, const gchar *label_text, const gchar *def
* (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)

17
src/document.c
View File

@ -124,6 +124,8 @@ static gboolean update_tags_from_buffer(GeanyDocument *doc);
* @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 @@ static GeanyDocument *document_create(const gchar *utf8_filename)
* @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 @@ static void replace_header_filename(GeanyDocument *doc)
*
* @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 @@ void document_rename_file(GeanyDocument *doc, const gchar *new_filename)
* @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 @@ GdkColor *document_get_status_color(GeanyDocument *doc)
/** 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;

22
src/editor.c
View File

@ -3692,7 +3692,9 @@ void editor_indicator_clear_errors(GeanyEditor *editor)
*
* @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 @@ void editor_indicator_clear(GeanyEditor *editor, gint indic)
* @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 @@ void editor_indicator_set_on_line(GeanyEditor *editor, gint indic, gint line)
* @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 @@ void editor_set_line_wrapping(GeanyEditor *editor, gboolean wrap)
/** 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 @@ static ScintillaObject *create_new_sci(GeanyEditor *editor)
/** 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();

5
src/editor.h
View File

@ -74,7 +74,10 @@ typedef enum
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. */

10
src/filetypes.c
View File

@ -1316,7 +1316,10 @@ gboolean filetype_has_tags(GeanyFiletype *ft)
/** 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 @@ void filetypes_read_extensions(void)
/** 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;

6
src/msgwindow.c
View File

@ -273,6 +273,8 @@ void msgwin_show_hide(gboolean show)
* @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 @@ static gboolean on_msgwin_button_press_event(GtkWidget *widget, GdkEventButton *
* @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 @@ void msgwin_switch_tab(gint tabnum, gboolean show)
*
* @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)
{

28
src/sciwrappers.c
View File

@ -684,7 +684,10 @@ void sci_set_tab_width(ScintillaObject * sci, gint width)
/** 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 @@ void sci_use_popup(ScintillaObject *sci, gboolean enable)
/** 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 @@ gboolean sci_get_readonly(ScintillaObject *sci)
/** 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 @@ gint sci_indicator_get(ScintillaObject *sci)
* @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 @@ void sci_indicator_fill(ScintillaObject *sci, gint pos, gint len)
* @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 @@ void sci_set_autoc_max_height(ScintillaObject *sci, gint val)
/** 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);

28
src/ui_utils.c
View File

@ -690,7 +690,10 @@ static void on_doc_sensitive_widget_destroy(GtkWidget *widget, G_GNUC_UNUSED gpo
/** 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 @@ GtkWidget *ui_button_new_with_image(const gchar *stock_id, const gchar *text)
/** 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 @@ static void entry_clear_icon_press_cb(GtkEntry *entry, gint icon_pos, GdkEvent *
* 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 @@ void ui_auto_separator_add_ref(GeanyAutoSeparator *autosep, GtkWidget *item)
*
* @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 @@ void ui_widget_set_tooltip_text(GtkWidget *widget, const gchar *text)
* @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 @@ static gboolean progress_bar_pulse(gpointer data)
* 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 @@ void ui_progress_bar_start(const gchar *text)
}
/** 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));

5
src/ui_utils.h
View File

@ -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);

15
src/utils.c
View File

@ -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 @@ gdouble utils_scale_round(gdouble val, gdouble factor)
*
* @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 @@ gint utils_strpos(const gchar *haystack, const gchar *needle)
* @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 @@ guint utils_string_replace_all(GString *haystack, const gchar *needle, const gch
/**
* 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 @@ guint utils_string_replace_all(GString *haystack, const gchar *needle, const gch
* @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)
{