SF.net SVN: geany:[4760] trunk

ntrel at users.sourceforge.net ntrel at xxxxx
Mon Mar 15 13:01:16 UTC 2010


Revision: 4760
          http://geany.svn.sourceforge.net/geany/?rev=4760&view=rev
Author:   ntrel
Date:     2010-03-15 13:01:16 +0000 (Mon, 15 Mar 2010)

Log Message:
-----------
Use 3rd person for more API dox.
Change 'This is a wrapper function for...' to 'Wraps...' in brief
descriptions.
Change 'After all...' to 'Afterwards...'.

Modified Paths:
--------------
    trunk/ChangeLog
    trunk/src/dialogs.c
    trunk/src/document.c
    trunk/src/filetypes.c
    trunk/src/main.c
    trunk/src/msgwindow.c
    trunk/src/navqueue.c
    trunk/src/sciwrappers.c
    trunk/src/utils.c
    trunk/src/utils.h

Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog	2010-03-13 12:04:49 UTC (rev 4759)
+++ trunk/ChangeLog	2010-03-15 13:01:16 UTC (rev 4760)
@@ -1,3 +1,14 @@
+2010-03-15  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
+
+ * src/utils.c, src/utils.h, src/sciwrappers.c, src/dialogs.c,
+   src/navqueue.c, src/msgwindow.c, src/filetypes.c, src/document.c,
+   src/main.c:
+   Use 3rd person for more API dox.
+   Change 'This is a wrapper function for...' to 'Wraps...' in brief
+   descriptions.
+   Change 'After all...' to 'Afterwards...'.
+
+
 2010-03-12  Nick Treleaven  <nick(dot)treleaven(at)btinternet(dot)com>
 
  * src/ui_utils.c:

Modified: trunk/src/dialogs.c
===================================================================
--- trunk/src/dialogs.c	2010-03-13 12:04:49 UTC (rev 4759)
+++ trunk/src/dialogs.c	2010-03-15 13:01:16 UTC (rev 4760)
@@ -541,7 +541,7 @@
 
 
 /**
- *  Show the Save As dialog for the current notebook page.
+ *  Shows the Save As dialog for the current notebook page.
  *
  *  @return @c TRUE if the file was saved, otherwise @c FALSE.
  **/
@@ -593,7 +593,7 @@
 
 
 /**
- *  Show a message box of the type @a type with @a text.
+ *  Shows a message box of the type @a type with @a text.
  *  On Unix-like systems a GTK message dialog box is shown, on Win32 systems a native Windows
  *  message dialog box is shown.
  *
@@ -945,7 +945,7 @@
 
 
 /**
- *  Show an input box to enter a numerical value using a GtkSpinButton.
+ *  Shows an input box to enter a numerical value using a GtkSpinButton.
  *  If the dialog is aborted, @a value remains untouched.
  *
  *  @param title The dialog title.
@@ -1454,7 +1454,7 @@
 
 
 /**
- *  Show a question message box with @a text and Yes/No buttons.
+ *  Shows a question message box with @a text and Yes/No buttons.
  *  On Unix-like systems a GTK message dialog box is shown, on Win32 systems a native Windows
  *  message dialog box is shown.
  *

Modified: trunk/src/document.c
===================================================================
--- trunk/src/document.c	2010-03-13 12:04:49 UTC (rev 4759)
+++ trunk/src/document.c	2010-03-15 13:01:16 UTC (rev 4760)
@@ -119,13 +119,14 @@
 #endif
 
 /**
- * Find and retrieve a document with the given filename from the document list.
+ * Finds a document whose @c real_path field matches the given filename.
  *
  * @param realname The filename to search, which should be identical to the
  * string returned by @c tm_get_real_path().
  *
  * @return The matching document, or @c NULL.
  * @note This is only really useful when passing a @c TMWorkObject::file_name.
+ * @see GeanyDocument::real_path.
  * @see document_find_by_filename().
  *
  * @since 0.15
@@ -165,7 +166,7 @@
 
 
 /**
- *  Find and retrieve a document with the given filename from the document list.
+ *  Finds a document with the given filename.
  *  This matches either an exact GeanyDocument::file_name string, or variant
  *  filenames with relative elements in the path (e.g. @c "/dir/..//name" will
  *  match @c "/name").
@@ -235,7 +236,7 @@
 
 
 /**
- *  Find and retrieve the document for the given notebook page @a page_num.
+ *  Finds the document for the given notebook page @a page_num.
  *
  *  @param page_num The notebook page number to search.
  *
@@ -256,7 +257,7 @@
 
 
 /**
- *  Find and retrieve the current document.
+ *  Finds the current document.
  *
  *  @return A pointer to the current document or @c NULL if there are no opened documents.
  **/
@@ -341,7 +342,7 @@
 
 
 /**
- *  Update the tab labels, the status bar, the window title and some save-sensitive buttons
+ *  Updates the tab labels, the status bar, the window title and some save-sensitive buttons
  *  according to the document's save state.
  *  This is called by Geany mostly when opening or saving files.
  *
@@ -591,7 +592,7 @@
 
 
 /**
- *  Close the given document.
+ *  Closes the given document.
  *
  *  @param doc The document to remove.
  *
@@ -608,7 +609,7 @@
 
 
 /**
- *  Remove the given notebook tab at @a page_num and clear all related information
+ *  Removes the given notebook tab at @a page_num and clears all related information
  *  in the document list.
  *
  *  @param page_num The notebook page number to remove.
@@ -697,7 +698,7 @@
 
 /**
  *  Creates a new document.
- *  After all, the "document-new" signal is emitted for plugins.
+ *  Afterwards, the @c "document-new" signal is emitted for plugins.
  *
  *  @param utf8_filename The file name in UTF-8 encoding, or @c NULL to open a file as "untitled".
  *  @param ft The filetype to set or @c NULL to detect it from @a filename if not @c NULL.
@@ -775,8 +776,8 @@
 
 
 /**
- *  Open a document specified by @a locale_filename.
- *  After all, the "document-open" signal is emitted for plugins.
+ *  Opens a document specified by @a locale_filename.
+ *  Afterwards, the @c "document-open" signal is emitted for plugins.
  *
  *  @param locale_filename The filename of the document to load, in locale encoding.
  *  @param readonly Whether to open the document in read-only mode.
@@ -1733,12 +1734,12 @@
 
 
 /**
- *  Save the document. Saving includes replacing tabs by spaces,
+ *  Saves the document. Saving includes replacing tabs by spaces,
  *  stripping trailing spaces and adding a final new line at the end of the file (all only if
- *  user enabled these features). Then the "document-before-save" signal is emitted,
+ *  user enabled these features). Then the @c "document-before-save" signal is emitted,
  *  allowing plugins to modify the document before it is saved, and data is
  *  actually written to disk. The filetype is set again or auto-detected if it wasn't set yet.
- *  After all, the "document-save" signal is emitted for plugins.
+ *  Afterwards, the @c "document-save" signal is emitted for plugins.
  *
  *  If the file is not modified, this functions does nothing unless force is set to @c TRUE.
  *

Modified: trunk/src/filetypes.c
===================================================================
--- trunk/src/filetypes.c	2010-03-13 12:04:49 UTC (rev 4759)
+++ trunk/src/filetypes.c	2010-03-15 13:01:16 UTC (rev 4760)
@@ -1067,7 +1067,7 @@
 #ifdef HAVE_PLUGINS
 /* Currently only used by external plugins (e.g. geanyprj). */
 /**
- *  Detect filetype based on a shebang line in the file, or the filename extension.
+ *  Detects filetype based on a shebang line in the file or the filename extension.
  *
  *  @param utf8_filename The filename in UTF-8 encoding.
  *

Modified: trunk/src/main.c
===================================================================
--- trunk/src/main.c	2010-03-13 12:04:49 UTC (rev 4759)
+++ trunk/src/main.c	2010-03-15 13:01:16 UTC (rev 4760)
@@ -386,7 +386,7 @@
 
 
 /**
- *  Check whether the main window has been realized.
+ *  Checks whether the main window has been realized.
  *  This is an easy indicator whether Geany is right now starting up (main window is not
  *  yet realized) or whether it has finished the startup process (main window is realized).
  *  This is because the main window is realized (i.e. actually drawn on the screen) at the

Modified: trunk/src/msgwindow.c
===================================================================
--- trunk/src/msgwindow.c	2010-03-13 12:04:49 UTC (rev 4759)
+++ trunk/src/msgwindow.c	2010-03-15 13:01:16 UTC (rev 4760)
@@ -352,7 +352,7 @@
 
 
 /**
- *  Log a status message *without* setting the status bar.
+ *  Logs a status message *without* setting the status bar.
  *  (Use ui_set_statusbar() to display text on the statusbar)
  *
  *  @param format @c printf()-style format string.

Modified: trunk/src/navqueue.c
===================================================================
--- trunk/src/navqueue.c	2010-03-13 12:04:49 UTC (rev 4759)
+++ trunk/src/navqueue.c	2010-03-15 13:01:16 UTC (rev 4760)
@@ -136,7 +136,7 @@
 
 
 /**
- *  Add old file position and new file position to the navqueue, then goes to the new position.
+ *  Adds old file position and new file position to the navqueue, then goes to the new position.
  *
  *  @param old_doc The document of the previous position, if set as invalid (@c NULL) then no old
  *         position is set

Modified: trunk/src/sciwrappers.c
===================================================================
--- trunk/src/sciwrappers.c	2010-03-13 12:04:49 UTC (rev 4759)
+++ trunk/src/sciwrappers.c	2010-03-15 13:01:16 UTC (rev 4760)
@@ -1012,7 +1012,7 @@
 
 
 /**
- *  Set the current indicator. This is necessary to define an indicator for a range of text or
+ *  Sets the current indicator. This is necessary to define an indicator for a range of text or
  *  clearing indicators for a range of text.
  *
  *  @param sci Scintilla widget.
@@ -1035,7 +1035,7 @@
 
 
 /**
- *  Clear a range of text from the currently set indicator.
+ *  Clears the currently set indicator from a range of text.
  *  Starting at @a pos, @a len characters long.
  *  In order to make this function properly, you need to set the current indicator before with
  *  @ref sci_indicator_set().

Modified: trunk/src/utils.c
===================================================================
--- trunk/src/utils.c	2010-03-13 12:04:49 UTC (rev 4759)
+++ trunk/src/utils.c	2010-03-15 13:01:16 UTC (rev 4760)
@@ -214,7 +214,7 @@
 
 
 /**
- *  Write the given @a text into a file with @a filename.
+ *  Writes the given @a text into a file with @a filename.
  *  If the file doesn't exist, it will be created.
  *  If it already exists, it will be overwritten.
  *
@@ -508,7 +508,7 @@
 
 
 /**
- *  Remove the extension from @a filename and return the result in a newly allocated string.
+ *  Removes the extension from @a filename and return the result in a newly allocated string.
  *
  *  @param filename The filename to operate on.
  *
@@ -1322,8 +1322,8 @@
 
 
 /**
- *  Create a directory if it doesn't already exist.
- *  Create intermediate parent directories as needed, too.
+ *  Creates a directory if it doesn't already exist.
+ *  Creates intermediate parent directories as needed, too.
  *  The permissions of the created directory are set 0700.
  *
  *  @param path The path of the directory to create, in locale encoding.
@@ -1549,7 +1549,7 @@
 
 
 /**
- *  This is a wrapper function for g_spawn_sync() and internally calls this function on Unix-like
+ *  Wraps g_spawn_sync() and internally calls this function on Unix-like
  *  systems. On Win32 platforms, it uses the Windows API.
  *
  *  @param dir The child's current working directory, or @a NULL to inherit parent's.
@@ -1597,7 +1597,7 @@
 
 
 /**
- *  This is a wrapper function for g_spawn_async() and internally calls this function on Unix-like
+ *  Wraps g_spawn_async() and internally calls this function on Unix-like
  *  systems. On Win32 platforms, it uses the Windows API.
  *
  *  @param dir The child's current working directory, or @a NULL to inherit parent's.
@@ -1801,7 +1801,7 @@
 
 
 /**
- *  Replace or remove characters from a string in place.
+ *  Removes characters from a string, in place.
  *
  *  @param string String to search.
  *  @param chars Characters to remove.

Modified: trunk/src/utils.h
===================================================================
--- trunk/src/utils.h	2010-03-13 12:04:49 UTC (rev 4759)
+++ trunk/src/utils.h	2010-03-15 13:01:16 UTC (rev 4760)
@@ -38,7 +38,7 @@
 	(G_LIKELY((ptr)) && G_LIKELY((ptr)[0]))
 
 /**
- *  Free's @a ptr (if not @c NULL), then assigns @a result to it.
+ *  Frees @a ptr (if not @c NULL), then assigns @a result to it.
  *  @a result can be an expression using the 'old' value of @a ptr.
  *  It prevents a memory leak compared with: @code ptr = func(ptr); @endcode
  **/


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