* add doxygen docs to header file

* add C++ macros to header file


git-svn-id: file:///home/lennart/svn/public/pulseaudio/trunk@920 fefdeb5f-60dc-0310-8127-8f9354f1896f

src/polyp/util.c

@@ -57,7 +57,7 @@
 
 #include <polyp/xmalloc.h>
 #include <polypcore/log.h>
-#include <polypcore/util.h>
+#include <polypcore/core-util.h>
 
 #include "util.h"
 
@@ -67,7 +67,6 @@
 #define PATH_SEP '\\'
 #endif
 
-/* Return the current username in the specified string buffer. */
 char *pa_get_user_name(char *s, size_t l) {
     char *p;
     char buf[1024];
@@ -110,7 +109,6 @@ char *pa_get_user_name(char *s, size_t l) {
     return pa_strlcpy(s, p, l);
 }
 
-/* Return the current hostname in the specified buffer. */
 char *pa_get_host_name(char *s, size_t l) {
     assert(s && l > 0);
     if (gethostname(s, l) < 0) {
@@ -121,7 +119,6 @@ char *pa_get_host_name(char *s, size_t l) {
     return s;
 }
 
-/* Return the home directory of the current user */
 char *pa_get_home_dir(char *s, size_t l) {
     char *e;
 
@@ -195,8 +192,6 @@ struct timeval *pa_gettimeofday(struct timeval *tv) {
 #endif
 }
 
-/* Calculate the difference between the two specfified timeval
- * timestamsps. */
 pa_usec_t pa_timeval_diff(const struct timeval *a, const struct timeval *b) {
     pa_usec_t r;
     assert(a && b);
@@ -221,7 +216,6 @@ pa_usec_t pa_timeval_diff(const struct timeval *a, const struct timeval *b) {
     return r;
 }
 
-/* Compare the two timeval structs and return 0 when equal, negative when a < b, positive otherwse */
 int pa_timeval_cmp(const struct timeval *a, const struct timeval *b) {
     assert(a && b);
 
@@ -240,7 +234,6 @@ int pa_timeval_cmp(const struct timeval *a, const struct timeval *b) {
     return 0;
 }
 
-/* Return the time difference between now and the specified timestamp */
 pa_usec_t pa_timeval_age(const struct timeval *tv) {
     struct timeval now;
     assert(tv);
@@ -248,8 +241,7 @@ pa_usec_t pa_timeval_age(const struct timeval *tv) {
     return pa_timeval_diff(pa_gettimeofday(&now), tv);
 }
 
-/* Add the specified time inmicroseconds to the specified timeval structure */
+struct timeval* pa_timeval_add(struct timeval *tv, pa_usec_t v) {
-void pa_timeval_add(struct timeval *tv, pa_usec_t v) {
     unsigned long secs;
     assert(tv);
     
@@ -264,11 +256,10 @@ void pa_timeval_add(struct timeval *tv, pa_usec_t v) {
         tv->tv_sec++;
         tv->tv_usec -= 1000000;
     }
+
+    return tv;
 }
 
-/* Return the binary file name of the current process. Works on Linux
- * only. This shoul be used for eyecandy only, don't rely on return
- * non-NULL! */
 char *pa_get_binary_name(char *s, size_t l) {
 
 #ifdef HAVE_READLINK
@@ -295,8 +286,6 @@ char *pa_get_binary_name(char *s, size_t l) {
 #endif
 }
 
-/* Return a pointer to the filename inside a path (which is the last
- * component). */
 const char *pa_path_get_filename(const char *p) {
     char *fn;
 
@@ -306,7 +295,6 @@ const char *pa_path_get_filename(const char *p) {
     return (const char*) p;
 }
 
-/* Return the fully qualified domain name in *s */
 char *pa_get_fqdn(char *s, size_t l) {
     char hn[256];
 #ifdef HAVE_GETADDRINFO    
@@ -332,7 +320,6 @@ char *pa_get_fqdn(char *s, size_t l) {
 #endif
 }
 
-/* Wait t milliseconds */
 int pa_msleep(unsigned long t) {
 #ifdef OS_IS_WIN32
     Sleep(t);

src/polyp/util.h

@@ -26,23 +26,54 @@
 #include <inttypes.h>
 
 #include <polyp/sample.h>
+#include <polyp/cdecl.h>
+
+/** \file
+ * Assorted utility functions */
+
+PA_C_DECL_BEGIN
 
 struct timeval;
 
+/** Return the current username in the specified string buffer. */
 char *pa_get_user_name(char *s, size_t l);
+
+/** Return the current hostname in the specified buffer. */
 char *pa_get_host_name(char *s, size_t l);
+
+/** Return the fully qualified domain name in s */
 char *pa_get_fqdn(char *s, size_t l);
+
+/** Return the home directory of the current user */
 char *pa_get_home_dir(char *s, size_t l);
 
+/** Return the binary file name of the current process. This is not
+ * supported on all architectures, in which case NULL is returned. */
 char *pa_get_binary_name(char *s, size_t l);
+
+/** Return a pointer to the filename inside a path (which is the last
+ * component). */
 const char *pa_path_get_filename(const char *p);
 
+/** Return the current timestamp, just like UNIX gettimeofday() */
 struct timeval *pa_gettimeofday(struct timeval *tv);
-pa_usec_t pa_timeval_diff(const struct timeval *a, const struct timeval *b);
-int pa_timeval_cmp(const struct timeval *a, const struct timeval *b);
-pa_usec_t pa_timeval_age(const struct timeval *tv);
-void pa_timeval_add(struct timeval *tv, pa_usec_t v);
 
+/** Calculate the difference between the two specified timeval
+ * structs. */
+pa_usec_t pa_timeval_diff(const struct timeval *a, const struct timeval *b);
+
+/** Compare the two timeval structs and return 0 when equal, negative when a < b, positive otherwse */
+int pa_timeval_cmp(const struct timeval *a, const struct timeval *b);
+
+/** Return the time difference between now and the specified timestamp */
+pa_usec_t pa_timeval_age(const struct timeval *tv);
+
+/** Add the specified time inmicroseconds to the specified timeval structure */
+struct timeval* pa_timeval_add(struct timeval *tv, pa_usec_t v);
+
+/** Wait t milliseconds */
 int pa_msleep(unsigned long t);
 
+PA_C_DECL_END
+
 #endif