changeset 37065:b28b632efeef

Cosmetic: Revise a few comments.

--- a/gui/app/app.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/app/app.c	Thu Apr 24 11:31:31 2014 +0000
@@ -252,7 +252,7 @@
  * @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)
 {

--- a/gui/dialog/dialog.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/dialog/dialog.c	Thu Apr 24 11:31:31 2014 +0000
@@ -59,8 +59,8 @@
  *
  * @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)
  */

--- a/gui/skin/font.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/skin/font.c	Thu Apr 24 11:31:31 2014 +0000
@@ -213,9 +213,9 @@
 }
 
 /**
- * @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

--- a/gui/skin/skin.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/skin/skin.c	Thu Apr 24 11:31:31 2014 +0000
@@ -63,8 +63,7 @@
  * @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 @@
  *
  *        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 @@
  * @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()
  */

--- a/gui/ui/render.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/ui/render.c	Thu Apr 24 11:31:31 2014 +0000
@@ -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 @@
  * @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)
 {

--- a/gui/util/bitmap.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/util/bitmap.c	Thu Apr 24 11:31:31 2014 +0000
@@ -66,7 +66,7 @@
  * @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 @@
  * @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)

--- a/gui/util/list.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/util/list.c	Thu Apr 24 11:31:31 2014 +0000
@@ -47,7 +47,7 @@
  *         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 @@
 }
 
 /**
- * @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 @@
 }
 
 /**
- * @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
  */

--- a/gui/util/list.h	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/util/list.h	Thu Apr 24 11:31:31 2014 +0000
@@ -52,7 +52,7 @@
 /// @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);

--- a/gui/util/misc.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/util/misc.c	Thu Apr 24 11:31:31 2014 +0000
@@ -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
  *

--- a/gui/util/string.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/util/string.c	Thu Apr 24 11:31:31 2014 +0000
@@ -173,7 +173,7 @@
  * @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 @@
 }
 
 /**
- * @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 @@
 }
 
 /**
- * @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 @@
 }
 
 /**
- * @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 @@
  *
  *        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 @@
  * @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
  *

--- a/gui/win32/interface.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/win32/interface.c	Thu Apr 24 11:31:31 2014 +0000
@@ -93,9 +93,9 @@
 /**
  * @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 @@
 /**
  * @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)
 {

--- a/gui/win32/skinload.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/win32/skinload.c	Thu Apr 24 11:31:31 2014 +0000
@@ -103,8 +103,7 @@
  * @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)
 {

--- a/gui/win32/widgetrender.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/win32/widgetrender.c	Thu Apr 24 11:31:31 2014 +0000
@@ -129,10 +129,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)
 {

--- a/gui/wm/ws.c	Thu Apr 24 06:42:02 2014 +0000
+++ b/gui/wm/ws.c	Thu Apr 24 11:31:31 2014 +0000
@@ -954,7 +954,7 @@
  *
  * @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)
 {