SF.net SVN: geany:[2951] trunk - Commits

16 Sep 2008

Revision: 2951
          http://geany.svn.sourceforge.net/geany/?rev=2951&view=rev
Author:   ntrel
Date:     2008-09-16 15:37:50 +0000 (Tue, 16 Sep 2008)
Log Message:
-----------
Fix Doxygen 1.5.4 undocumented parameter warnings.
Improve dox for sciwrappers.c.
Correct sci_grap_focus() misspelling.
(Merged from split-window-plugin branch).
Modified Paths:
--------------
    trunk/ChangeLog
    trunk/src/filetypes.c
    trunk/src/keybindings.c
    trunk/src/sciwrappers.c
    trunk/src/sciwrappers.h
Modified: trunk/ChangeLog
===================================================================

--- trunk/ChangeLog	2008-09-16 15:21:46 UTC (rev 2950)
+++ trunk/ChangeLog	2008-09-16 15:37:50 UTC (rev 2951)
@@ -1,3 +1,13 @@
+2008-09-16  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
+
+ * src/keybindings.c, src/sciwrappers.c, src/sciwrappers.h,
+   src/filetypes.c:
+   Fix Doxygen 1.5.4 undocumented parameter warnings.
+   Improve dox for sciwrappers.c.
+   Correct sci_grap_focus() misspelling.
+   (Merged from split-window-plugin branch).
+
+
 2008-09-15  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
* src/editor.c:
Modified: trunk/src/filetypes.c
===================================================================
--- trunk/src/filetypes.c	2008-09-16 15:21:46 UTC (rev 2950)
+++ trunk/src/filetypes.c	2008-09-16 15:37:50 UTC (rev 2951)
@@ -1133,7 +1133,9 @@
 }
-/** Find a filetype pointer from its @c name field. */
+/** Find a filetype pointer from its @c name field.
+ * @param name Filetype name.
+ * @return The filetype found, or @c NULL. */
 GeanyFiletype *filetypes_lookup_by_name(const gchar *name)
 {
    GeanyFiletype *ft;
Modified: trunk/src/keybindings.c
===================================================================
--- trunk/src/keybindings.c	2008-09-16 15:21:46 UTC (rev 2950)
+++ trunk/src/keybindings.c	2008-09-16 15:37:50 UTC (rev 2951)
@@ -97,7 +97,15 @@
 /* This is used to set default keybindings on startup but at this point we don't want to
  * assign the keybinding to the menu_item (apply_kb_accel) otherwise it can't be overridden
  * by user keybindings anymore */
-/** Simple convenience function to fill a GeanyKeyBinding struct item. */
+/** Simple convenience function to fill a GeanyKeyBinding struct item.
+ * @param group
+ * @param key_id
+ * @param callback
+ * @param key
+ * @param mod
+ * @param name
+ * @param label
+ * @param menu_item */
 void keybindings_set_item(GeanyKeyGroup *group, gsize key_id,
    	GeanyKeyCallback callback, guint key, GdkModifierType mod,
    	gchar *name, gchar *label, GtkWidget *menu_item)
Modified: trunk/src/sciwrappers.c
===================================================================
--- trunk/src/sciwrappers.c	2008-09-16 15:21:46 UTC (rev 2950)
+++ trunk/src/sciwrappers.c	2008-09-16 15:37:50 UTC (rev 2951)
@@ -196,7 +196,9 @@
    }
 }
-/** Set all text. */
+/** Set all text.
+ * @param sci Scintilla widget.
+ * @param text Text. */
 void sci_set_text(ScintillaObject* sci, const gchar* text)
 {
    if( text != NULL ){ /* if null text is passed to scintilla will segfault */
@@ -369,35 +371,47 @@
 }
-/** Get line number from character index. */
+/** Get line number from position.
+ * @param sci Scintilla widget.
+ * @param position Position. */ 
 gint sci_get_line_from_position(ScintillaObject* sci, gint position )
 {
    return SSM(sci, SCI_LINEFROMPOSITION, position, 0);
 }
-/** Get column number relative to the start of the line that @a position is on. */
+/** Get column number relative to the start of the line that @a position is on.
+ * @param sci Scintilla widget.
+ * @param position Position. */ 
 gint sci_get_col_from_position(ScintillaObject* sci, gint position )
 {
    return SSM(sci, SCI_GETCOLUMN, position, 0);
 }
-/** Get character index for the start of @a line. */
+/** Get position for the start of @a line.
+ * @param sci Scintilla widget.
+ * @param line Line.
+ * @return Position. */
 gint sci_get_position_from_line(ScintillaObject* sci, gint line )
 {
    return SSM(sci, SCI_POSITIONFROMLINE, line, 0);
 }
-/** Get cursor position. */
+/** Get cursor position.
+ * @param sci Scintilla widget.
+ * @return Position. */
 gint sci_get_current_position(ScintillaObject* sci )
 {
    return SSM(sci, SCI_GETCURRENTPOS, 0, 0);
 }
-/** Set the cursor position. */
+/** Set the cursor position.
+ * @param sci Scintilla widget.
+ * @param position Position.
+ * @param scroll_to_caret Whether to scroll the cursor in view. */
 void sci_set_current_position(ScintillaObject* sci, gint position, gboolean scroll_to_caret)
 {
    if (scroll_to_caret)
@@ -420,21 +434,26 @@
 }
-/** Get total number of lines. */
+/** Get total number of lines.
+ * @param sci Scintilla widget. */
 gint sci_get_line_count( ScintillaObject* sci )
 {
    return SSM(sci, SCI_GETLINECOUNT, 0, 0);
 }
-/** Set selection start position. */
+/** Set selection start position.
+ * @param sci Scintilla widget.
+ * @param position Position. */
 void sci_set_selection_start(ScintillaObject* sci, gint position)
 {
    SSM(sci, SCI_SETSELECTIONSTART, position, 0);
 }
-/** Set selection end position. */
+/** Set selection end position.
+ * @param sci Scintilla widget.
+ * @param position Position. */
 void sci_set_selection_end(ScintillaObject* sci, gint position)
 {
    SSM(sci, SCI_SETSELECTIONEND, position, 0);
@@ -471,28 +490,36 @@
 }
-/** Get position of selection start. */
+/** Get position of selection start.
+ * @param sci Scintilla widget.
+ * @return Position. */
 gint sci_get_selection_start(ScintillaObject* sci)
 {
    return SSM(sci, SCI_GETSELECTIONSTART,0,0);
 }
-/** Get position of selection end. */
+/** Get position of selection end.
+ * @param sci Scintilla widget.
+ * @return Position. */
 gint sci_get_selection_end(ScintillaObject* sci)
 {
    return SSM(sci, SCI_GETSELECTIONEND,0,0);
 }
-/** Replace selection. */
+/** Replace selection.
+ * @param sci Scintilla widget.
+ * @param text Text. */
 void sci_replace_sel(ScintillaObject* sci, const gchar* text)
 {
    SSM(sci, SCI_REPLACESEL,0, (sptr_t) text);
 }
-/** Get length of all text. */
+/** Get length of all text.
+ * @param sci Scintilla widget.
+ * @return Length. */
 gint sci_get_length(ScintillaObject* sci)
 {
    return SSM(sci,SCI_GETLENGTH,0,0);
@@ -505,14 +532,21 @@
 }
-/** Get line length. */
+/** Get line length.
+ * @param sci Scintilla widget.
+ * @param line Line number.
+ * @return Length. */
 gint sci_get_line_length(ScintillaObject* sci,gint line)
 {
    return SSM(sci,SCI_LINELENGTH, line,0);
 }
-/** Returns: a NULL-terminated copy of the line text. */
+/* TODO: rename/change to use buffer? Otherwise inconsistent with sci_get_text*(). */
+/** Get line contents.
+ * @param sci Scintilla widget.
+ * @param line_num Line number.
+ * @return A @c NULL-terminated copy of the line text. */
 gchar *sci_get_line(ScintillaObject* sci, gint line_num)
 {
    gint len = sci_get_line_length(sci, line_num);
@@ -524,23 +558,29 @@
 }
-/** The last char will be null terminated, so ensure @a text has been allocated @a len + 1
- * bytes. */
+/** Get all text.
+ * @param sci Scintilla widget.
+ * @param len Length of @a text buffer, usually sci_get_length() + 1.
+ * @param text Text buffer; must be allocated @a len + 1 bytes for null-termination. */
 void sci_get_text(ScintillaObject* sci, gint len, gchar* text)
 {
    SSM( sci, SCI_GETTEXT, len, (sptr_t) text );
 }
-/** Text must be allocated sci_get_selected_text_length() + 1, because
- * the selection will be NULL-terminated. */
+/** Get selected text.
+ * @param sci Scintilla widget.
+ * @param text Text buffer; must be allocated sci_get_selected_text_length() + 1 bytes
+ * for null-termination. */
 void sci_get_selected_text(ScintillaObject* sci, gchar* text)
 {
    SSM( sci, SCI_GETSELTEXT, 0, (sptr_t) text);
 }
-/** Get selected text length. */
+/** Get selected text length.
+ * @param sci Scintilla widget.
+ * @return Length. */
 gint sci_get_selected_text_length(ScintillaObject* sci)
 {
    return SSM( sci, SCI_GETSELTEXT, 0, 0);
@@ -561,14 +601,19 @@
 }
-/** Returns: whether @a line should be drawn on the screen (folding may have hidden it). */
+/** Check if a line is visible (folding may have hidden it).
+ * @param sci Scintilla widget.
+ * @param line Line number.
+ * @return Whether @a line will be drawn on the screen. */
 gboolean sci_get_line_is_visible(ScintillaObject* sci, gint line)
 {
    return SSM(sci,SCI_GETLINEVISIBLE, line,0);
 }
-/** Make the @a line visible (folding may have hidden it). */
+/** Make the @a line visible (folding may have hidden it).
+ * @param sci Scintilla widget.
+ * @param line Line number. */
 void sci_ensure_line_is_visible(ScintillaObject* sci, gint line)
 {
    SSM(sci,SCI_ENSUREVISIBLE,line,0);
@@ -637,14 +682,19 @@
 }
-/** Get display tab width. */
+/** Get display tab width (this is not indent width, see GeanyIndentPrefs).
+ * @param sci Scintilla widget.
+ * @return Width. */
 gint sci_get_tab_width(ScintillaObject * sci)
 {
    return SSM(sci, SCI_GETTABWIDTH, 0, 0);
 }
-/** Get character. */
+/** Get character.
+ * @param sci Scintilla widget.
+ * @param pos Position.
+ * @return Char. */
 gchar sci_get_char_at(ScintillaObject *sci, gint pos)
 {
    return (gchar) SSM(sci, SCI_GETCHARAT, pos, 0);
@@ -669,7 +719,10 @@
 }
-/** You can also call this has_selection. */
+/* TODO: rename to has_selection. */
+/** Check if there's a selection.
+ * @param sci Scintilla widget.
+ * @return Whether a selection is present. */
 gboolean sci_can_copy(ScintillaObject *sci)
 {
    if (SSM(sci, SCI_GETSELECTIONEND,0,0) - SSM(sci, SCI_GETSELECTIONSTART,0,0))
@@ -698,7 +751,8 @@
 }
-/** Scroll the cursor in view. */
+/** Scroll the cursor in view.
+ * @param sci Scintilla widget. */
 void sci_scroll_caret(ScintillaObject *sci)
 {
    SSM(sci, SCI_SCROLLCARET, 0, 0);
@@ -749,7 +803,10 @@
 }
-/** Get style number for @a position. */
+/** Get style ID for @a position.
+ * @param sci Scintilla widget.
+ * @param position Position.
+ * @return Style ID. */
 gint sci_get_style_at(ScintillaObject *sci, gint position)
 {
    return SSM(sci, SCI_GETSTYLEAT, position, 0);
@@ -774,7 +831,11 @@
 }
-/** Text will be zero terminated and must be allocated (end - start + 1) bytes. */
+/** Get text between @a start and @a end.
+ * @param sci Scintilla widget.
+ * @param start Start.
+ * @param end End.
+ * @param text Text will be zero terminated and must be allocated (end - start + 1) bytes. */
 void sci_get_text_range(ScintillaObject *sci, gint start, gint end, gchar *text)
 {
    struct TextRange tr;
@@ -797,14 +858,17 @@
 }
-/** Insert text. */
+/** Insert text.
+ * @param sci Scintilla widget.
+ * @param pos Position.
+ * @param text Text. */
 void sci_insert_text(ScintillaObject *sci, gint pos, const gchar *text)
 {
    SSM(sci, SCI_INSERTTEXT, pos, (sptr_t) text);
 }
-void sci_grap_focus(ScintillaObject *sci)
+void sci_grab_focus(ScintillaObject *sci)
 {
    SSM(sci, SCI_GRABFOCUS, 0, 0);
 }
@@ -865,7 +929,9 @@
 }
-/** Get current line number. */
+/** Get current line number.
+ * @param sci Scintilla widget.
+ * @return Line number. */
 gint sci_get_current_line(ScintillaObject *sci)
 {
    return SSM(sci, SCI_LINEFROMPOSITION, SSM(sci, SCI_GETCURRENTPOS, 0, 0), 0);
@@ -918,7 +984,11 @@
    SSM(sci, SCI_AUTOCSETMAXHEIGHT, val, 0);
 }
-/** Find a matching brace at @a pos. */
+/** Find a matching brace at @a pos.
+ * @param sci Scintilla widget.
+ * @param pos Position.
+ * @return Matching brace position. */
+/* TODO: rename _matching_brace */
 gint sci_find_bracematch(ScintillaObject *sci, gint pos)
 {
    return SSM(sci, SCI_BRACEMATCH, pos, 0);
@@ -949,13 +1019,17 @@
    return SSM(sci, SCI_GETLINESELENDPOSITION, line, 0);
 }
-/** Get selection mode. */
+/** Get selection mode.
+ * @param sci Scintilla widget.
+ * @return Selection mode. */
 gint sci_get_selection_mode(ScintillaObject *sci)
 {
    return SSM(sci, SCI_GETSELECTIONMODE, 0, 0);
 }
-/** Set selection mode. */
+/** Set selection mode.
+ * @param sci Scintilla widget.
+ * @param mode Mode. */
 void sci_set_selection_mode(ScintillaObject *sci, gint mode)
 {
    SSM(sci, SCI_SETSELECTIONMODE, mode, 0);
Modified: trunk/src/sciwrappers.h
===================================================================
--- trunk/src/sciwrappers.h	2008-09-16 15:21:46 UTC (rev 2950)
+++ trunk/src/sciwrappers.h	2008-09-16 15:37:50 UTC (rev 2951)
@@ -141,7 +141,7 @@
 void				sci_selection_duplicate		(ScintillaObject * sci);
 void				sci_line_duplicate			(ScintillaObject * sci);
 void				sci_insert_text				(ScintillaObject * sci, gint pos, const gchar *text);
-void				sci_grap_focus				(ScintillaObject * sci);
+void				sci_grab_focus				(ScintillaObject * sci);
 void				sci_set_cursor				(ScintillaObject * sci, gint cursor);
 void				sci_target_from_selection	(ScintillaObject * sci);
 void				sci_target_start			(ScintillaObject * sci, gint start);
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.

    