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.