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

Use 3rd person for more API dox.

Browse Source 
Change 'This is a wrapper function for...' to 'Wraps...' in brief
descriptions.
Change 'After all...' to 'Afterwards...'.



git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/trunk@4760 ea778897-0a13-0410-b9d1-a72fbfd435f5
This commit is contained in:
Nick Treleaven 2010-03-15 13:01:16 +00:00
parent e8b0d5b25f
commit a190e1bfb7
10 changed files with 43 additions and 31 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

11
ChangeLog
View File

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

8
src/dialogs.c
View File

@ -541,7 +541,7 @@ static gboolean gtk_show_save_as(void)
/**
* 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 @@ static void show_msgbox_dialog(GtkWidget *dialog, GtkMessageType type, GtkWindow
/**
* 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 @@ gchar *dialogs_show_input(const gchar *title, const gchar *label_text,
/**
* 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 @@ static gint show_prompt(GtkWidget *parent,
/**
* 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.
*

27
src/document.c
View File

@ -119,13 +119,14 @@ static gboolean update_tags_from_buffer(GeanyDocument *doc);
#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 @@ static gchar *get_real_path_from_utf8(const gchar *utf8_filename)
/**
* 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 @@ gint document_get_notebook_page(GeanyDocument *doc)
/**
* 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 @@ GeanyDocument *document_get_from_page(guint page_num)
/**
* 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 @@ void document_update_tab_label(GeanyDocument *doc)
/**
* 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 @@ static GeanyDocument *document_create(const gchar *utf8_filename)
/**
* Close the given document.
* Closes the given document.
*
* @param doc The document to remove.
*
@ -608,7 +609,7 @@ gboolean document_close(GeanyDocument *doc)
/**
* 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 @@ GeanyDocument *document_new_file_if_non_open(void)
/**
* 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 @@ GeanyDocument *document_new_file(const gchar *utf8_filename, GeanyFiletype *ft,
/**
* 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 @@ static gchar *write_data_to_disk(GeanyDocument *doc, const gchar *locale_filenam
/**
* 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.
*

2
src/filetypes.c
View File

@ -1067,7 +1067,7 @@ GeanyFiletype *filetypes_detect_from_document(GeanyDocument *doc)
#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.
*

2
src/main.c
View File

@ -386,7 +386,7 @@ static void setup_paths(void)
/**
* 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

2
src/msgwindow.c
View File

@ -352,7 +352,7 @@ void msgwin_msg_add_string(gint msg_color, gint line, GeanyDocument *doc, const
/**
* 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.

2
src/navqueue.c
View File

@ -136,7 +136,7 @@ static void add_new_position(const gchar *utf8_filename, gint pos)
/**
* 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

4
src/sciwrappers.c
View File

@ -1012,7 +1012,7 @@ gint sci_get_first_visible_line(ScintillaObject *sci)
/**
* 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 @@ void sci_indicator_fill(ScintillaObject *sci, gint pos, gint len)
/**
* 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().

14
src/utils.c
View File

@ -214,7 +214,7 @@ gboolean utils_is_opening_brace(gchar c, gboolean include_angles)
/**
* 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 @@ gboolean utils_str_equal(const gchar *a, const gchar *b)
/**
* 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 @@ gchar **utils_strv_new(const gchar *first, ...)
/**
* 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 @@ static gboolean check_error(GError **error)
/**
* 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 @@ gboolean utils_spawn_sync(const gchar *dir, gchar **argv, gchar **env, GSpawnFla
/**
* 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 @@ void utils_tidy_path(gchar *filename)
/**
* 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.

2
src/utils.h
View File

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