SF.net SVN: geany:[4010] trunk
eht16 at users.sourceforge.net
eht16 at xxxxx
Tue Jul 21 22:12:16 UTC 2009
Revision: 4010
http://geany.svn.sourceforge.net/geany/?rev=4010&view=rev
Author: eht16
Date: 2009-07-21 22:12:13 +0000 (Tue, 21 Jul 2009)
Log Message:
-----------
Continue unifying usage of @a and @c markup elements in API docs.
Modified Paths:
--------------
trunk/ChangeLog
trunk/src/dialogs.c
trunk/src/document.c
trunk/src/editor.c
trunk/src/encodings.c
trunk/src/filetypes.c
trunk/src/keybindings.h
trunk/src/main.c
trunk/src/msgwindow.c
trunk/src/navqueue.c
trunk/src/plugindata.h
Modified: trunk/ChangeLog
===================================================================
--- trunk/ChangeLog 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/ChangeLog 2009-07-21 22:12:13 UTC (rev 4010)
@@ -6,6 +6,11 @@
* src/main.c, src/prefs.c, src/toolbar.c, src/toolbar.h:
Show/hide the toolbar without a restart when the setting in the
preferences dialog is changed (closes #2824785).
+ * src/dialogs.c, src/document.c, src/editor.c, src/encodings.c,
+ src/filetypes.c, src/keybindings.h, src/main.c, src/msgwindow.c,
+ src/navqueue.c, src/plugindata.h, src/prefs.c, src/toolbar.c,
+ src/toolbar.h:
+ Continue unifying usage of @a and @c markup elements in API docs.
2009-07-21 Nick Treleaven <nick(dot)treleaven(at)btinternet(dot)com>
Modified: trunk/src/dialogs.c
===================================================================
--- trunk/src/dialogs.c 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/src/dialogs.c 2009-07-21 22:12:13 UTC (rev 4010)
@@ -542,7 +542,7 @@
/**
* Show the Save As dialog for the current notebook page.
*
- * @return @a TRUE if the file was saved, otherwise @a FALSE.
+ * @return @c TRUE if the file was saved, otherwise @c FALSE.
**/
gboolean dialogs_show_save_as()
{
@@ -592,14 +592,14 @@
/**
- * Show a message box of the type @c type with @c text.
+ * Show 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.
*
- * @param type A GtkMessageType, e.g. GTK_MESSAGE_INFO, GTK_MESSAGE_WARNING,
- * GTK_MESSAGE_QUESTION, GTK_MESSAGE_ERROR.
+ * @param type A @c GtkMessageType, e.g. @c GTK_MESSAGE_INFO, @c GTK_MESSAGE_WARNING,
+ * @c GTK_MESSAGE_QUESTION, @c GTK_MESSAGE_ERROR.
* @param text Printf()-style format string.
- * @param ... Arguments for the @c text format string.
+ * @param ... Arguments for the @a text format string.
**/
void dialogs_show_msgbox(GtkMessageType type, const gchar *text, ...)
{
@@ -913,18 +913,18 @@
/**
* Show an input box to enter a numerical value using a GtkSpinButton.
- * If the dialog is aborted, @c value remains untouched.
+ * If the dialog is aborted, @a value remains untouched.
*
* @param title The dialog title.
* @param label_text The shown dialog label.
* @param value The default value for the spin button and the return location of the entered value.
* Must be non-NULL.
- * @param min Minimum allowable value (see documentation for @a gtk_spin_button_new_with_range()).
- * @param max Maximum allowable value (see documentation for @a gtk_spin_button_new_with_range()).
+ * @param min Minimum allowable value (see documentation for @c gtk_spin_button_new_with_range()).
+ * @param max Maximum allowable value (see documentation for @c gtk_spin_button_new_with_range()).
* @param step Increment added or subtracted by spinning the widget
- * (see documentation for @a gtk_spin_button_new_with_range()).
+ * (see documentation for @c gtk_spin_button_new_with_range()).
*
- * @return @a TRUE if a value was entered and the dialog closed with 'OK'. @a FALSE otherwise.
+ * @return @c TRUE if a value was entered and the dialog closed with 'OK'. @c FALSE otherwise.
*
* @since 0.16
**/
@@ -1392,14 +1392,14 @@
/**
- * Show a question message box with @c text and Yes/No buttons.
+ * Show 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.
*
* @param text Printf()-style format string.
- * @param ... Arguments for the @c text format string.
+ * @param ... Arguments for the @a text format string.
*
- * @return @a TRUE if the user answered with Yes, otherwise @a FALSE.
+ * @return @c TRUE if the user answered with Yes, otherwise @c FALSE.
**/
gboolean dialogs_show_question(const gchar *text, ...)
{
Modified: trunk/src/document.c
===================================================================
--- trunk/src/document.c 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/src/document.c 2009-07-21 22:12:13 UTC (rev 4010)
@@ -124,7 +124,7 @@
* @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 NULL.
+ * @return The matching document, or @c NULL.
* @note This is only really useful when passing a @c TMWorkObject::file_name.
* @see document_find_by_filename().
*
@@ -172,7 +172,7 @@
*
* @param utf8_filename The filename to search (in UTF-8 encoding).
*
- * @return The matching document, or NULL.
+ * @return The matching document, or @c NULL.
* @see document_find_by_real_path().
**/
GeanyDocument *document_find_by_filename(const gchar *utf8_filename)
@@ -236,7 +236,7 @@
*
* @param page_num The notebook page number to search.
*
- * @return The corresponding document for the given notebook page, or NULL.
+ * @return The corresponding document for the given notebook page, or @c NULL.
**/
GeanyDocument *document_get_from_page(guint page_num)
{
@@ -287,12 +287,12 @@
/**
* Returns the last part of the filename of the given GeanyDocument. The result is also
- * truncated to a maximum of @c length characters in case the filename is very long.
+ * truncated to a maximum of @a length characters in case the filename is very long.
*
* @param doc The document to use.
* @param length The length of the resulting string or -1 to use a default value.
*
- * @return The ellipsized last part of the filename of @c doc, should be freed when no
+ * @return The ellipsized last part of the filename of @a doc, should be freed when no
* longer needed.
*
* @since 0.17
@@ -571,7 +571,7 @@
*
* @param doc The document to remove.
*
- * @return @a TRUE if the document was actually removed or @a FALSE otherwise.
+ * @return @c TRUE if the document was actually removed or @c FALSE otherwise.
*
* @since 0.15
**/
@@ -589,7 +589,7 @@
*
* @param page_num The notebook page number to remove.
*
- * @return @a TRUE if the document was actually removed or @a FALSE otherwise.
+ * @return @c TRUE if the document was actually removed or @c FALSE otherwise.
**/
gboolean document_remove_page(guint page_num)
{
@@ -757,7 +757,7 @@
* @param ft The %filetype for the %document or @c NULL to auto-detect the %filetype.
* @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
*
- * @return The document opened or NULL.
+ * @return The document opened or @c NULL.
**/
GeanyDocument *document_open_file(const gchar *locale_filename, gboolean readonly,
GeanyFiletype *ft, const gchar *forced_enc)
@@ -1380,13 +1380,13 @@
}
/**
- * Reloads the @a document with the specified file encoding
+ * Reloads the document with the specified file encoding
* @a forced_enc or @c NULL to auto-detect the file encoding.
*
* @param doc The document to reload.
* @param forced_enc The file encoding to use or @c NULL to auto-detect the file encoding.
*
- * @return @a TRUE if the %document was actually reloaded or @a FALSE otherwise.
+ * @return @c TRUE if the %document was actually reloaded or @c FALSE otherwise.
**/
gboolean document_reload_file(GeanyDocument *doc, const gchar *forced_enc)
{
@@ -1681,7 +1681,7 @@
/**
- * Save the @a document. Saving includes replacing tabs by spaces,
+ * Save 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). The filetype is set again or auto-detected if it wasn't
* set yet. After all, the "document-save" signal is emitted for plugins.
@@ -2711,13 +2711,13 @@
/**
- * Gets the status colour of the document, or NULL if default widget colouring should be used.
+ * Gets the status colour of the document, or @c NULL if default widget colouring should be used.
* Returned colours are red if the document has changes, green is the document is read-only
- * or simply NULL if the document is unmodified but writable.
+ * or simply @c NULL if the document is unmodified but writable.
*
* @param doc The document to use.
*
- * @return The colour for the document or NULL if the default colour should be used. The colour
+ * @return The colour for the document or @c NULL if the default colour should be used. The colour
* object is owned by Geany and should not be modified or freed.
*
* @since 0.16
Modified: trunk/src/editor.c
===================================================================
--- trunk/src/editor.c 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/src/editor.c 2009-07-21 22:12:13 UTC (rev 4010)
@@ -1379,18 +1379,18 @@
/**
- * Finds the word at the position specified by @c pos. If any word is found, it is returned.
+ * Finds the word at the position specified by @a pos. If any word is found, it is returned.
* Otherwise NULL is returned.
* Additional wordchars can be specified to define what to consider as a word.
*
* @param editor The editor to operate on.
* @param pos The position where the word should be read from.
- * Maybe @a -1 to use the current position.
+ * Maybe @c -1 to use the current position.
* @param wordchars The wordchars to separate words. wordchars mean all characters to count
- * as part of a word. Maybe @a NULL to use the default wordchars,
+ * as part of a word. Maybe @c NULL to use the default wordchars,
* see @ref GEANY_WORDCHARS.
*
- * @return A newly-allocated string containing the word at the given @c pos or NULL.
+ * @return A newly-allocated string containing the word at the given @a pos or @c NULL.
* Should be freed when no longer needed.
*
* @since 0.16
@@ -4071,7 +4071,7 @@
/**
- * Sets an indicator on the range specified by @c start and @c end.
+ * Sets an indicator on the range specified by @a start and @a end.
* No error checking or whitespace removal is performed, this should be done by the calling
* function if necessary.
*
Modified: trunk/src/encodings.c
===================================================================
--- trunk/src/encodings.c 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/src/encodings.c 2009-07-21 22:12:13 UTC (rev 4010)
@@ -461,7 +461,7 @@
* @param fast @c TRUE to only convert the input and skip extended checks on the converted string.
*
* @return If the conversion was successful, a newly allocated nul-terminated string,
- * which must be freed with g_free(). Otherwise @c NULL.
+ * which must be freed with @c g_free(). Otherwise @c NULL.
**/
gchar *encodings_convert_to_utf8_from_charset(const gchar *buffer, gsize size,
const gchar *charset, gboolean fast)
@@ -516,7 +516,7 @@
* @param used_encoding return location of the detected encoding of the input string, or @c NULL.
*
* @return If the conversion was successful, a newly allocated nul-terminated string,
- * which must be freed with g_free(). Otherwise @c NULL.
+ * which must be freed with @c g_free(). Otherwise @c NULL.
**/
gchar *encodings_convert_to_utf8(const gchar *buffer, gsize size, gchar **used_encoding)
{
Modified: trunk/src/filetypes.c
===================================================================
--- trunk/src/filetypes.c 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/src/filetypes.c 2009-07-21 22:12:13 UTC (rev 4010)
@@ -946,7 +946,7 @@
*
* @param utf8_filename The filename in UTF-8 encoding.
*
- * @return The detected filetype for @c utf8_filename or @c filetypes[GEANY_FILETYPES_NONE]
+ * @return The detected filetype for @a utf8_filename or @c filetypes[GEANY_FILETYPES_NONE]
* if it could not be detected.
**/
GeanyFiletype *filetypes_detect_from_file(const gchar *utf8_filename)
@@ -1340,7 +1340,7 @@
}
-/** Find a filetype pointer from its @c name field.
+/** Find a filetype pointer from its @a name field.
* @param name Filetype name.
* @return The filetype found, or @c NULL.
*
Modified: trunk/src/keybindings.h
===================================================================
--- trunk/src/keybindings.h 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/src/keybindings.h 2009-07-21 22:12:13 UTC (rev 4010)
@@ -53,7 +53,7 @@
{
const gchar *name; /**< Group name used in the configuration file, such as @c "html_chars" */
const gchar *label; /**< Group label used in the preferences dialog keybindings tab */
- gsize count; /**< Count of GeanyKeyBinding structs in @a keys */
+ gsize count; /**< Count of GeanyKeyBinding structs in @c keys */
GeanyKeyBinding *keys; /**< Fixed array of GeanyKeyBinding structs */
}
GeanyKeyGroup;
Modified: trunk/src/main.c
===================================================================
--- trunk/src/main.c 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/src/main.c 2009-07-21 22:12:13 UTC (rev 4010)
@@ -388,7 +388,7 @@
* Initialises the gettext translation system.
* This is a convenience function to set up gettext for internationalisation support
* in external plugins. You should call this function early in @ref plugin_init().
- * If the macro HAVE_LOCALE_H is defined, @a setlocale(LC_ALL, "") is called.
+ * If the macro HAVE_LOCALE_H is defined, @c setlocale(LC_ALL, "") is called.
* The codeset for the message translations is set to UTF-8.
*
* Note that this function only setups the gettext textdomain for you. You still have
@@ -396,11 +396,11 @@
* working properly.
*
* @param locale_dir The location where the translation files should be searched. This is
- * usually the @a LOCALEDIR macro, defined by the build system.
- * E.g. $prefix/share/locale.
+ * usually the @c LOCALEDIR macro, defined by the build system.
+ * E.g. @c $prefix/share/locale.
* Only used on non-Windows systems. On Windows, the directory is determined
* by @c g_win32_get_package_installation_directory().
- * @param package The package name, usually this is the @a GETTEXT_PACKAGE macro,
+ * @param package The package name, usually this is the @c GETTEXT_PACKAGE macro,
* defined by the build system.
*
* @since 0.16
Modified: trunk/src/msgwindow.c
===================================================================
--- trunk/src/msgwindow.c 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/src/msgwindow.c 2009-07-21 22:12:13 UTC (rev 4010)
@@ -289,11 +289,11 @@
/**
* Adds a new message in the messages tab treeview in the messages window.
- * If @c line and @c doc are set, clicking on this line jumps into the file which is specified
- * by @c doc into the line specified with @c line.
+ * If @a line and @a doc are set, clicking on this line jumps into the file which is specified
+ * by @a doc into the line specified with @a line.
*
* @param msg_color A color to be used for the text. It must be an element of #MsgColors.
- * @param line The document's line where the message belongs to. Set to -1 to ignore.
+ * @param line The document's line where the message belongs to. Set to @c -1 to ignore.
* @param doc The document. Set to @c NULL to ignore.
* @param format @c printf()-style format string.
* @param ... Arguments for the @c format string.
@@ -1028,7 +1028,7 @@
/**
* Switches to the given notebook tab of the messages window and shows the messages window
- * if it was previously hidden and @c show is set to @a TRUE.
+ * if it was previously hidden and @a show is set to @c TRUE.
*
* @param tabnum An index of a tab in the messages window. Valid values are all elements of
* #MessageWindowTabNum.
@@ -1062,10 +1062,10 @@
}
/**
- * Removes all messages from a tab specified by @c tabnum in the messages window.
+ * Removes all messages from a tab specified by @a tabnum in the messages window.
*
* @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.
+ * Valid values are @c MSG_STATUS, @c MSG_COMPILER and @c MSG_MESSAGE.
*
* @since 0.15
**/
Modified: trunk/src/navqueue.c
===================================================================
--- trunk/src/navqueue.c 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/src/navqueue.c 2009-07-21 22:12:13 UTC (rev 4010)
@@ -143,7 +143,7 @@
* @param new_doc The document of the new position, must be valid.
* @param line the line number of the new position. It is counted with 1 as the first line, not 0.
*
- * @return @a TRUE if the cursor has changed the position to @a line or @a FALSE otherwise.
+ * @return @c TRUE if the cursor has changed the position to @a line or @c FALSE otherwise.
**/
gboolean navqueue_goto_line(GeanyDocument *old_doc, GeanyDocument *new_doc, gint line)
{
Modified: trunk/src/plugindata.h
===================================================================
--- trunk/src/plugindata.h 2009-07-21 22:10:42 UTC (rev 4009)
+++ trunk/src/plugindata.h 2009-07-21 22:12:13 UTC (rev 4010)
@@ -166,11 +166,11 @@
* Fields set and owned by the plugin. */
typedef struct PluginFields
{
- /** Bitmask of PluginFlags. */
+ /** Bitmask of @c PluginFlags. */
PluginFlags flags;
/** Pointer to a plugin's menu item which will be automatically enabled/disabled when there
- * are no open documents and PLUGIN_IS_DOCUMENT_SENSITIVE is set.
- * This is required if using PLUGIN_IS_DOCUMENT_SENSITIVE, ignored otherwise */
+ * are no open documents and @c PLUGIN_IS_DOCUMENT_SENSITIVE is set.
+ * This is required if using @c PLUGIN_IS_DOCUMENT_SENSITIVE, ignored otherwise */
GtkWidget *menu_item;
}
PluginFields;
@@ -552,7 +552,7 @@
/* Deprecated aliases */
#ifndef GEANY_DISABLE_DEPRECATED
-/** NULL-safe way to get the index of @a doc_ptr in the documents array. */
+/** @c NULL-safe way to get the index of @a doc_ptr in the documents array. */
#define DOC_IDX(doc_ptr) \
(doc_ptr ? doc_ptr->index : -1)
#define DOC_IDX_VALID(doc_idx) \
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