Author: ib
Date: Thu Apr 24 13:31:31 2014
New Revision: 37161
Log:
Cosmetic: Revise a few comments.
Modified:
trunk/gui/app/app.c
trunk/gui/dialog/dialog.c
trunk/gui/skin/font.c
trunk/gui/skin/skin.c
trunk/gui/ui/render.c
trunk/gui/util/bitmap.c
trunk/gui/util/list.c
trunk/gui/util/list.h
trunk/gui/util/misc.c
trunk/gui/util/string.c
trunk/gui/win32/interface.c
trunk/gui/win32/skinload.c
trunk/gui/win32/widgetrender.c
trunk/gui/wm/ws.c
Modified: trunk/gui/app/app.c
==============================================================================
--- trunk/gui/app/app.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/app/app.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -252,7 +252,7 @@ void btnSet(int event, int state)
* @brief Retrieve the value of the (main) item belonging to an event.
*
* @param event event
- * @param value pointer to a variable to store the value (if event has been found)
+ * @param value memory location to store the value (if event has been found)
*/
void btnValue(int event, float *value)
{
Modified: trunk/gui/dialog/dialog.c
==============================================================================
--- trunk/gui/dialog/dialog.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/dialog/dialog.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -59,8 +59,8 @@ static int gtkInitialized;
*
* @param theme theme to load the icon from
* @param size size of the icon to load
- * @param gdkIcon location to store a pointer to the created pixmap
- * @param gdkIconMask location to store a pointer to the created mask
+ * @param gdkIcon memory location to store a pointer to the created pixmap
+ * @param gdkIconMask memory location to store a pointer to the created mask
*
* @return #True (ok) or #False (error)
*/
Modified: trunk/gui/skin/font.c
==============================================================================
--- trunk/gui/skin/font.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/skin/font.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -213,9 +213,9 @@ int fntFindID(char *name)
}
/**
- * @brief Get the #bmpFont::Fnt index of the character @a *str points to.
+ * @brief Get the #bmpFont::Fnt index of the character @a str points to.
*
- * Move pointer @a *str to the character according to @a direction
+ * Move pointer @a str to the character according to @a direction
* afterwards.
*
* @param id font ID
Modified: trunk/gui/skin/skin.c
==============================================================================
--- trunk/gui/skin/skin.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/skin/skin.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -63,8 +63,7 @@ static guiItem *currWinItems;
* @brief Print a legacy information on an entry.
*
* @param old identifier (and deprecated entry)
- * @param data pointer to additional data necessary for checking and
- * to print the information on @a old
+ * @param data string necessary for checking and to print the information on @a old
*/
static void skin_legacy(const char *old, const char *data)
{
@@ -595,7 +594,7 @@ static int item_menu(char *in)
*
* Parameters: button,bwidth,bheight,phases,numphases,[x0,y0,x1,y1,]default,x,y,width,height,message
*
- * @param item pointer to item to store the parameters in
+ * @param item memory location of an item to store the parameters in
* @param in definition to be analyzed
*
* @note item->type is already available.
@@ -1136,7 +1135,7 @@ static _item skinItem[] = {
* @brief Read a skin @a image file.
*
* @param fname filename (with path)
- * @param img pointer suitable to store the image data
+ * @param img memory location to store the image data
*
* @return return code of #bpRead()
*/
Modified: trunk/gui/ui/render.c
==============================================================================
--- trunk/gui/ui/render.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/ui/render.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -52,10 +52,10 @@
* @param how 0 (cut file path and extension),
* 1 (additionally, convert lower case) or
* 2 (additionally, convert upper case)
- * @param fname pointer to a buffer to receive the converted Filename
- * @param maxlen size of @a fname buffer
+ * @param fname memory location of a buffer to receive the converted Filename
+ * @param maxlen size of the @a fname buffer
*
- * @return pointer to @a fname buffer
+ * @return pointer to the @a fname buffer
*/
static char *TranslateFilename(int how, char *fname, size_t maxlen)
{
@@ -427,7 +427,7 @@ static void PutImage(int x, int y, uint3
* @param window pointer to a ws window structure of the window to be rendered
* @param items pointer to the array of items
* @param till maximum index in use for the @a items, i.e. number of last item in array
- * @param drawbuf pointer to the @a window's draw buffer
+ * @param drawbuf memory location of the @a window's draw buffer
*/
void RenderAll(wsWindow *window, guiItem *items, int till, char *drawbuf)
{
Modified: trunk/gui/util/bitmap.c
==============================================================================
--- trunk/gui/util/bitmap.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/util/bitmap.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -66,7 +66,7 @@ static const char *fExist(const char *fn
* @brief Read and decode a PNG file into bitmap data.
*
* @param fname filename (with path)
- * @param img pointer suitable to store the image data
+ * @param img memory location to store the image data
*
* @return 0 (ok), 1 (decoding error), 2 (open error), 3 (file too big),
* 4 (out of memory), 5 (read error), 6 (avcodec alloc error)
@@ -230,7 +230,7 @@ static int convert_ARGB(guiImage *img)
* @brief Read a PNG file.
*
* @param fname filename (with path, but may lack extension)
- * @param img pointer suitable to store the image data
+ * @param img memory location to store the image data
*
* @return 0 (ok), -1 (color depth too low), -2 (not accessible),
* -5 (#pngRead() error) or -8 (#convert_ARGB() error)
Modified: trunk/gui/util/list.c
==============================================================================
--- trunk/gui/util/list.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/util/list.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -47,7 +47,7 @@ static urlItem *urlList;
* pointer to current list item (ITEM command) or
* NULL (DELETE or unknown command)
*
- * @note PLAYLIST_ITEM_GET_POS returns the position number as pointer
+ * @note PLAYLIST_ITEM_GET_POS returns the position number as pointer value
* (if @a data is NULL the last position number, i.e. number of items),
* and position 0 means "not found"
*/
@@ -269,9 +269,9 @@ void *listMgr(int cmd, void *data)
}
/**
- * @brief Set list to @a entry.
+ * @brief Set string list to @a entry.
*
- * @param list pointer to the char pointer list
+ * @param list pointer to the string list
* @param entry the new (and only) element of the list
*
* @note Actually, a new list will be created and the old list will be freed.
@@ -298,11 +298,11 @@ void listSet(char ***list, const char *e
}
/**
- * @brief Replace the first element in list that starts with @a search.
+ * @brief Replace the first element in a string list that starts with @a search.
*
* @note If no such element is found, @a replace will be appended.
*
- * @param list pointer to the char pointer list
+ * @param list pointer to the string list
* @param search element to search
* @param replace replacement element
*/
Modified: trunk/gui/util/list.h
==============================================================================
--- trunk/gui/util/list.h Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/util/list.h Thu Apr 24 13:31:31 2014 (r37161)
@@ -52,7 +52,7 @@ typedef struct urlItem {
/// @name List manager (playlist, URL list)
void *listMgr(int cmd, void *data);
-/// @name Char pointer list operations
+/// @name String list operations
//@{
void listRepl(char ***list, const char *search, const char *replace);
void listSet(char ***list, const char *entry);
Modified: trunk/gui/util/misc.c
==============================================================================
--- trunk/gui/util/misc.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/util/misc.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -28,7 +28,7 @@
/**
* @brief Read characters from @a file.
*
- * @param str pointer to a buffer to receive the read characters
+ * @param str memory location of a buffer to receive the read characters
* @param size number of characters read at the most (including a terminating null-character)
* @param file file to read from
*
Modified: trunk/gui/util/string.c
==============================================================================
--- trunk/gui/util/string.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/util/string.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -173,7 +173,7 @@ char *decomment(char *in)
* @brief Extract a part of a string delimited by a separator character.
*
* @param in string to be analyzed
- * @param out pointer suitable to store the extracted part
+ * @param out memory location of a buffer suitable to store the extracted part
* @param sep separator character
* @param num number of separator characters to be skipped before extraction starts
* @param maxout maximum length of extracted part (including the trailing null byte)
@@ -215,7 +215,7 @@ int cutInt(char *in, char sep, int num)
}
/**
- * @brief A strchr() that can handle NULL pointers.
+ * @brief A strchr() that can handle NULL pointer arguments.
*
* @param str string to examine
* @param c character to find
@@ -231,7 +231,7 @@ char *gstrchr(const char *str, int c)
}
/**
- * @brief A strcmp() that can handle NULL pointers.
+ * @brief A strcmp() that can handle NULL pointer arguments.
*
* @param a string to be compared
* @param b string which is compared
@@ -249,7 +249,7 @@ int gstrcmp(const char *a, const char *b
}
/**
- * @brief A strncmp() that can handle NULL pointers.
+ * @brief A strncmp() that can handle NULL pointer arguments.
*
* @param a string to be compared
* @param b string which is compared
@@ -290,7 +290,7 @@ char *gstrdup(const char *str)
*
* The string is duplicated by calling #gstrdup().
*
- * @param old pointer to a variable suitable to store the new pointer
+ * @param old memory location to store the new pointer
* @param str string to be duplicated
*
* @note @a *old is freed prior to the assignment.
@@ -305,7 +305,7 @@ void setdup(char **old, const char *str)
* @brief Assign a newly allocated string
* containing the path created from a directory and a filename.
*
- * @param old pointer to a variable suitable to store the new pointer
+ * @param old memory location to store the new pointer
* @param dir directory
* @param name filename
*
Modified: trunk/gui/win32/interface.c
==============================================================================
--- trunk/gui/win32/interface.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/win32/interface.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -93,9 +93,9 @@ mixer_t *mixer = NULL;
/**
* @brief Convert a Windows style path to a file name into an Unix style one.
*
- * @param filename pointer to the file path to be converted
+ * @param filename file path string to be converted
*
- * @return pointer to the converted file path
+ * @return converted file path string
*/
static char *unix_name (char *win_filename)
{
@@ -129,9 +129,9 @@ static char *unix_name (char *win_filena
/**
* @brief Convert a Windows style device name into an Unix style one.
*
- * @param device pointer to the device name to be converted
+ * @param device device name to be converted
*
- * @return pointer to the converted device name
+ * @return converted device name
*/
static char *unix_device (char *device)
{
Modified: trunk/gui/win32/skinload.c
==============================================================================
--- trunk/gui/win32/skinload.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/win32/skinload.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -103,8 +103,7 @@ static int linenumber;
* @brief Print a legacy information on an entry.
*
* @param old identifier (and deprecated entry)
- * @param data pointer to additional data necessary for checking and
- * to print the information on @a old
+ * @param data string necessary for checking and to print the information on @a old
*/
static void skin_legacy (const char *old, const char *data)
{
Modified: trunk/gui/win32/widgetrender.c
==============================================================================
--- trunk/gui/win32/widgetrender.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/win32/widgetrender.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -129,10 +129,10 @@ static void stringreplace(char *dest, co
* @param how 0 (cut file path and extension),
* 1 (additionally, convert lower case) or
* 2 (additionally, convert upper case)
- * @param fname pointer to a buffer to receive the converted Filename
- * @param maxlen size of @a fname buffer
+ * @param fname memory location of a buffer to receive the converted Filename
+ * @param maxlen size of the @a fname buffer
*
- * @return pointer to @a fname buffer
+ * @return pointer to the @a fname buffer
*/
static char *TranslateFilename (int how, char *fname, size_t maxlen)
{
Modified: trunk/gui/wm/ws.c
==============================================================================
--- trunk/gui/wm/ws.c Thu Apr 24 08:42:02 2014 (r37160)
+++ trunk/gui/wm/ws.c Thu Apr 24 13:31:31 2014 (r37161)
@@ -954,7 +954,7 @@ void wsWindowShape(wsWindow *win, char *
*
* @param display display
* @param Win window
- * @param icon pointer to the icons
+ * @param icon pointer to the icon collection
*/
void wsWindowIcon(Display *display, Window Win, guiIcon_t *icon)
{
