From: mquinson <mquinson@48e7efb5-ca39-0410-a469-dd3cf9ba447f>
Date: Mon, 4 Jun 2007 13:53:03 +0000 (+0000)
Subject: document xbt_str
X-Git-Tag: v3.3~1807
X-Git-Url: http://info.iut-bm.univ-fcomte.fr/pub/gitweb/simgrid.git/commitdiff_plain/9e291a3a66a2c277895e78b3921c068436e7f9a1

document xbt_str


git-svn-id: svn+ssh://scm.gforge.inria.fr/svn/simgrid/simgrid/trunk@3553 48e7efb5-ca39-0410-a469-dd3cf9ba447f
---

diff --git a/doc/module-xbt.doc b/doc/module-xbt.doc
index 61ffc473e4..671715649e 100644
--- a/doc/module-xbt.doc
+++ b/doc/module-xbt.doc
@@ -3,6 +3,7 @@
    The XBT functionalities fall into several categories:
     - Portability support
       - \ref XBT_syscall
+      - \ref XBT_str
     - Grounding features
       - \ref XBT_ex
       - \ref XBT_log
@@ -37,6 +38,7 @@
   @{ */
 
      /** @defgroup XBT_syscall Malloc and friends */
+     /** @defgroup XBT_str     String related functions */
      /** @defgroup XBT_ex     Exception support */
      /** @defgroup XBT_log    Logging support */
      /** @defgroup XBT_error  Assert macro familly */
diff --git a/include/xbt/str.h b/include/xbt/str.h
index dbb5f8090e..0b4cb72179 100644
--- a/include/xbt/str.h
+++ b/include/xbt/str.h
@@ -11,8 +11,6 @@
 #include "xbt/misc.h"
 #include "xbt/dynar.h"
 
-
-
 #ifndef XBT_STR_H
 #define XBT_STR_H
 
@@ -22,13 +20,39 @@
 
 SG_BEGIN_DECL()
 
+/** @addtogroup XBT_str
+ *  @brief String manipulation functions
+ * 
+ * This module defines several string related functions. We redefine some quite classical 
+ * functions on the platforms were they are not nativaly defined (such as getline() or 
+ * asprintf()), while some other are a bit more exotic. 
+ * @{
+ */
+  
 /* snprintf related functions */
+/** @brief print to allocated string (reimplemented when not provided by the system)
+ * 
+ * The functions asprintf() and vasprintf() are analogues of
+ * sprintf() and vsprintf(), except that they allocate a string large
+ * enough to hold the output including the terminating null byte, and
+ * return a pointer to it via the first parameter.  This pointer
+ * should be passed to free(3) to release the allocated storage when
+ * it is no longer needed.
+ */
 XBT_PUBLIC(int) asprintf  (char **ptr, const char *fmt, /*args*/ ...) _XBT_GNUC_PRINTF(2,3);
+/** @brief print to allocated string (reimplemented when not provided by the system)
+ * 
+ * See asprintf()
+ */
 XBT_PUBLIC(int) vasprintf (char **ptr, const char *fmt, va_list ap);
+/** @brief print to allocated string
+ * 
+ * Works just like asprintf(), but returns a pointer to the newly created string
+ */
 XBT_PUBLIC(char*) bprintf   (const char*fmt, ...) _XBT_GNUC_PRINTF(1,2);
 
 /* the gettext function. It gets redefined here only if not yet available */
-#if defined(_WIN32) || !defined(__GNUC__)
+#if defined(_WIN32) || !defined(__GNUC__) || defined(DOXYGEN)
 XBT_PUBLIC(long) getline(char **lineptr, size_t *n, FILE *stream);
 #endif
 
@@ -44,6 +68,8 @@ XBT_PUBLIC(char *) xbt_str_join(xbt_dynar_t dynar, const char *sep);
 XBT_PUBLIC(void) xbt_str_strip_spaces(char *);
 XBT_PUBLIC(char *) xbt_str_diff(char *a, char *b);
 
+/**@}*/
+
 SG_END_DECL()
 
 #endif /* XBT_STR_H */
diff --git a/src/xbt/xbt_str.c b/src/xbt/xbt_str.c
index a949895305..811f1d951c 100644
--- a/src/xbt/xbt_str.c
+++ b/src/xbt/xbt_str.c
@@ -7,12 +7,6 @@
 /* This program is free software; you can redistribute it and/or modify it
  * under the terms of the license (GNU LGPL) which comes with this package. 
  */
-
-/* Returns the string without leading whitespaces (xbt_str_ltrim), 
- * trailing whitespaces (xbt_str_rtrim),
- * or both leading and trailing whitespaces (xbt_str_trim). 
- * (in-place modification of the string)
- */
   
 #include "xbt/misc.h"
 #include "xbt/sysdep.h"
@@ -260,7 +254,22 @@ char *xbt_str_join(xbt_dynar_t dyn, const char*sep) {
   return res;
 }
    
-#ifndef HAVE_GETLINE
+#if !defined(HAVE_GETLINE) || defined(DOXYGEN)
+/** @brief Get a single line from the stream (reimplementation of the GNU getline)
+ * 
+ * This is a redefinition of the GNU getline function, used on platforms where it does not exists.
+ * 
+ * getline() reads an entire line from stream, storing the address of the buffer 
+ * containing the text into *buf.  The buffer is null-terminated and includes 
+ * the newline character, if one was found.
+ * 
+ * If *buf is NULL, then getline() will allocate a buffer for storing the line, 
+ * which should be freed by the user program.  Alternatively, before calling getline(), 
+ * *buf can contain a pointer to a malloc()-allocated buffer *n bytes in size.  If the buffer 
+ * is not large enough to hold the line, getline() resizes it with realloc(), updating *buf and *n 
+ * as necessary.  In either case, on a successful call, *buf and *n will be updated to 
+ * reflect the buffer address and allocated size respectively.
+ */
 long getline(char **buf, size_t *n, FILE *stream) {
    
    int i, ch;