Cleanup doxygen style.
authorMatthias Bolte <matthias.bolte@googlemail.com>
Sat, 25 Apr 2009 12:51:59 +0000 (14:51 +0200)
committerMatthias Bolte <matthias.bolte@googlemail.com>
Sat, 25 Apr 2009 12:51:59 +0000 (14:51 +0200)
Signed-off-by: Matthias Bolte <matthias.bolte@googlemail.com>

33 files changed:
Doxyfile
HACKING
cli/Makefile
cli/command.c
cli/command.h
cli/core.c
cli/help.c
cli/option.c
cli/option.h
cli/token.c
cli/token.h
include/libvsccli/command.h
include/libvsccli/core.h
include/libvsccli/help.h
include/libvsccli/libvsccli.h
include/libvsccli/option.h
include/libvsccli/types.h
include/libvscmisc/assert.h
include/libvscmisc/debug.h
include/libvscmisc/error.h
include/libvscmisc/filesystem.h
include/libvscmisc/libvscmisc.h
include/libvscmisc/list.h
include/libvscmisc/memory.h
include/libvscmisc/string.h
include/libvscmisc/types.h
include/libvscremote/libvscremote.h
misc/Makefile
misc/list.c
misc/memory.c
misc/string.c
remote/Makefile
remote/remote.c

index 6da229c..78d5186 100644 (file)
--- a/Doxyfile
+++ b/Doxyfile
@@ -137,7 +137,7 @@ SHORT_NAMES            = NO
 # comments will behave just like regular Qt-style comments
 # (thus requiring an explicit @brief command for a brief description.)
 
-JAVADOC_AUTOBRIEF      = YES
+JAVADOC_AUTOBRIEF      = NO
 
 # If the QT_AUTOBRIEF tag is set to YES then Doxygen will
 # interpret the first line (until the first dot) of a Qt-style
@@ -186,7 +186,7 @@ ALIASES                =
 # For instance, some of the names that are used will be different. The list
 # of all members will be omitted, etc.
 
-OPTIMIZE_OUTPUT_FOR_C  = NO
+OPTIMIZE_OUTPUT_FOR_C  = YES
 
 # Set the OPTIMIZE_OUTPUT_JAVA tag to YES if your project consists of Java
 # sources only. Doxygen will then generate output that is more tailored for
@@ -364,7 +364,7 @@ HIDE_IN_BODY_DOCS      = NO
 # to NO (the default) then the documentation will be excluded.
 # Set it to YES to include the internal documentation.
 
-INTERNAL_DOCS          = NO
+INTERNAL_DOCS          = YES
 
 # If the CASE_SENSE_NAMES tag is set to NO then Doxygen will only generate
 # file names in lower-case letters. If set to YES upper-case letters are also
@@ -470,13 +470,13 @@ SHOW_USED_FILES        = YES
 # then setting the SHOW_DIRECTORIES tag to YES will show the directory hierarchy
 # in the documentation. The default is NO.
 
-SHOW_DIRECTORIES       = NO
+SHOW_DIRECTORIES       = YES
 
 # Set the SHOW_FILES tag to NO to disable the generation of the Files page.
 # This will remove the Files entry from the Quick Index and from the
 # Folder Tree View (if specified). The default is YES.
 
-SHOW_FILES             = NO
+SHOW_FILES             = YES
 
 # Set the SHOW_NAMESPACES tag to NO to disable the generation of the
 # Namespaces page.
@@ -564,7 +564,7 @@ WARN_LOGFILE           =
 # directories like "/usr/src/myproject". Separate the files or directories
 # with spaces.
 
-INPUT                  = cli misc remote
+INPUT                  = include cli misc remote
 
 # This tag can be used to specify the character encoding of the source files
 # that doxygen parses. Internally doxygen uses the UTF-8 encoding, which is
diff --git a/HACKING b/HACKING
index de32896..374f2ed 100644 (file)
--- a/HACKING
+++ b/HACKING
@@ -16,3 +16,14 @@ GENERAL
   automatically spot simple errors
 - write code in a way so that valgrind is happy
 - ...
+
+DOXYGEN
+
+- if a function has a prototype in a header file and the implementation in a
+  source file then document it in the source file only
+- if an enum or macro is defined only in a header file document it there
+- use the /*! ... style, not the /** ... style
+- use the @brief style, not the \brief style
+- mark the brief line explicitly with @brief
+- mark internal functions and types with @internal
+- ...
index 33ea178..605f907 100644 (file)
@@ -29,7 +29,7 @@ LDFLAGS += -lreadline
 all: $(TARGET)
 
 clean:
-       rm -rf $(TARGET) $(OBJS)
+       rm -rf $(TARGET) $(OBJS) $(CLEAN_PATTERNS)
 
 install: install-target-lib
 
index 0bcf284..e14f5a3 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <string.h>
 
 #include <libvscmisc/assert.h>
index b471179..d4aa272 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_CLI__COMMAND__PRIVATE_H__
 #define __VSC_CLI__COMMAND__PRIVATE_H__
 
index 9daa9d2..aa29081 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <malloc.h>
 
 #include <readline/readline.h>
index 6e6cc75..6bc32a0 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <stdarg.h>
 #include <stdio.h>
 #include <string.h>
index dd080c4..d063277 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <string.h>
 
 #include <libvscmisc/assert.h>
index 749e2ec..50806db 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_CLI__OPTION__PRIVATE_H__
 #define __VSC_CLI__OPTION__PRIVATE_H__
 
index e0117b1..98e68a4 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <libvscmisc/assert.h>
 #include <libvscmisc/error.h>
 #include <libvscmisc/memory.h>
index b023cfa..6fd25aa 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_CLI__TOKEN_H__
 #define __VSC_CLI__TOKEN_H__
 
index e9660cd..410530d 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_CLI__COMMAND_H__
 #define __VSC_CLI__COMMAND_H__
 
index 622e4a1..6d18a09 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_CLI__CORE_H__
 #define __VSC_CLI__CORE_H__
 
index e255a3f..d2be0b1 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_CLI__HELP_H__
 #define __VSC_CLI__HELP_H__
 
index e3cf021..5fa587f 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_CLI_H__
 #define __VSC_CLI_H__
 
index e10ca90..9a47425 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_CLI__OPTION_H__
 #define __VSC_CLI__OPTION_H__
 
index 0b274dc..073991f 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_CLI__TYPES_H__
 #define __VSC_CLI__TYPES_H__
 
index 29d93ea..47ccfbd 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MISC__ASSERT_H__
 #define __VSC_MISC__ASSERT_H__
 
index 6702939..821ce01 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MISC__DEBUG_H__
 #define __VSC_MISC__DEBUG_H__
 
index 3003b56..35060bb 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MISC__ERROR_H__
 #define __VSC_MISC__ERROR_H__
 
@@ -53,11 +57,6 @@ vsc_error_init (struct VscError *error);
 void
 vsc_error_cleanup (struct VscError *error);
 
-/**
- * Returns the string representaion of the error code.
- *
- * The string must not be freed by the caller.
- */
 const char * /* error_string */
 vsc_error_string (enum VscErrorCode code);
 
index a28bed1..1c9ddf8 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MISC__FILESYSTEM_H__
 #define __VSC_MISC__FILESYSTEM_H__
 
index 03c8c49..80efaa5 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MISC_H__
 #define __VSC_MISC_H__
 
index 2b5b8c9..8a03e3a 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MISC__LIST_H__
 #define __VSC_MISC__LIST_H__
 
 extern "C" {
 #endif
 
-/**
- * Returns the last item from the list.
- */
 struct VscList * /* last_item */
 vsc_list_get_last (struct VscList *list);
 
-/**
- * Appends a duplicate of the item to the list.
- *
- * If an error occurs then the list is untouched.
- */
 void
 vsc_list_append (struct VscError *error, struct VscList **list,
                  struct VscList *item,
@@ -48,30 +44,14 @@ vsc_list_duplicate (struct VscError *error, const struct VscList *list,
                     VscList_DuplicateFunction duplicate_function,
                     VscList_FreeFunction free_function);
 
-/**
- * Looks up an item in the list.
- *
- * The first item for that the match function returns TRUE is returned. If no
- * match occurs NULL is returned.
- */
 struct VscList * /* item */
 vsc_list_lookup (const struct VscList *list,
                  VscList_MatchFunction match_function, void *match_data);
 
-/**
- * Removes the item from the list and frees it.
- *
- * If the list becomes empty then the pointer to the list is set to NULL.
- *
- * If the item is not in the list then the list is untouched.
- */
 void
 vsc_list_remove (struct VscList **list, struct VscList *item,
                  VscList_FreeFunction free_function);
 
-/**
- * Recursively frees the list and the pointer to the list is set to NULL.
- */
 void
 vsc_list_free (struct VscList **list, VscList_FreeFunction free_function);
 
index deeb1bb..0396139 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MISC__MEMORY_H__
 #define __VSC_MISC__MEMORY_H__
 
@@ -32,14 +36,6 @@ extern "C" {
 void *
 vsc_alloc (struct VscError *error, size_t size);
 
-/**
- * Frees the block of memory at which the pointer pointed at by ptrptr points
- * and sets the pointer pointed at by ptrptr to NULL.
- *
- * void *ptr = vsc_alloc (error, 42);
- * ...
- * vsc_free (&ptr);
- */
 void
 vsc_free (void *ptrptr);
 
index 8386f74..5993977 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MISC__STRING_H__
 #define __VSC_MISC__STRING_H__
 
@@ -37,12 +41,6 @@ vsc_strdup (struct VscError *error, const char *string);
 const char *
 vsc_strerror (int errnum);
 
-/**
- * Stricter version of strtol, returning an int as result.
- *
- * If tail is NULL there must be no non-number character at the end of the
- * string, otherwise an error occurs.
- */
 int
 vsc_strtoi (struct VscError *error, const char *string, char **tail, int base);
 
index c8f120c..91f28ad 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_MISC__TYPES_H__
 #define __VSC_MISC__TYPES_H__
 
index 9b85961..cc24ab3 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #ifndef __VSC_REMOTE_H__
 #define __VSC_REMOTE_H__
 
index b939052..3ef8b01 100644 (file)
@@ -23,7 +23,7 @@ TARGET   = libvscmisc.so
 all: $(TARGET)
 
 clean:
-       rm -rf $(TARGET) $(OBJS)
+       rm -rf $(TARGET) $(OBJS) $(CLEAN_PATTERNS)
 
 install: install-target-lib
 
index 6ee22d4..48514c0 100644 (file)
@@ -24,8 +24,8 @@
 #include "../include/libvscmisc/error.h"
 #include "../include/libvscmisc/list.h"
 
-/**
- * Returns the last item from the list.
+/*!
+ * @brief Returns the last item from the list.
  */
 struct VscList * /* last_item */
 vsc_list_get_last (struct VscList *list)
@@ -45,8 +45,8 @@ vsc_list_get_last (struct VscList *list)
        return item;
 }
 
-/**
- * Appends a duplicate of the item to the list.
+/*!
+ * @brief Appends a duplicate of the item to the list.
  *
  * If an error occurs then the list is untouched.
  */
@@ -105,8 +105,8 @@ vsc_list_duplicate (struct VscError *error, const struct VscList *list,
        return list_duplicate;
 }
 
-/**
- * Looks up an item in the list.
+/*!
+ * @brief Looks up an item in the list.
  *
  * The first item for that the match function returns TRUE is returned. If no
  * match occurs NULL is returned.
@@ -128,8 +128,8 @@ vsc_list_lookup (const struct VscList *list,
        return NULL;
 }
 
-/**
- * Removes the item from the list and frees it.
+/*!
+ * @brief Removes the item from the list and frees it.
  *
  * If the list becomes empty then the pointer to the list is set to NULL.
  *
@@ -170,8 +170,8 @@ vsc_list_remove (struct VscList **list, struct VscList *item,
        }
 }
 
-/**
- * Recursively frees the list and set the list pointer to NULL.
+/*!
+ * @brief Recursively frees the list and set the list pointer to NULL.
  */
 void
 vsc_list_free (struct VscList **list, VscList_FreeFunction free_function)
index 33e6e23..4e54773 100644 (file)
@@ -44,13 +44,15 @@ vsc_alloc (struct VscError *error, size_t size)
        return ptr;
 }
 
-/**
- * Frees the block of memory at which the pointer pointed at by ptrptr points
- * and sets the pointer pointed at by ptrptr to NULL.
+/*!
+ * @brief Frees the block of memory at which the pointer pointed at by ptrptr
+ *        points and sets the pointer pointed at by ptrptr to NULL.
  *
+ * @code
  * void *ptr = vsc_alloc (error, 42);
  * ...
  * vsc_free (&ptr);
+ * @endcode
  */
 void
 vsc_free (void *ptrptr)
index 3451215..5cf24b5 100644 (file)
@@ -155,8 +155,8 @@ vsc_strerror (int errnum)
        }
 }
 
-/**
- * Stricter version of strtol, returning an int as result.
+/*!
+ * @brief Stricter version of strtol, returning an int as result.
  *
  * If tail is NULL there must be no non-number character at the end of the
  * string, otherwise an error occurs.
index 5a88a2d..cbf0591 100644 (file)
@@ -26,7 +26,7 @@ CFLAGS  += -I ../include
 all: $(TARGET)
 
 clean:
-       rm -rf $(TARGET) $(OBJS)
+       rm -rf $(TARGET) $(OBJS) $(CLEAN_PATTERNS)
 
 install: install-target-lib
 
index 1d50d70..928aede 100644 (file)
  * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307  USA
  */
 
+/*!
+ * @file
+ */
+
 #include <termios.h>
 
 #include <xmlrpc-c/client.h>