More doxygen.

git-svn-id: https://pupnp.svn.sourceforge.net/svnroot/pupnp/trunk@373 119443c7-1b9e-41f8-b6fc-b9c35fce742c

Doxyfile

@@ -290,7 +290,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 

upnp/inc/String.h

@@ -4,7 +4,21 @@
 #define STRING_H
 
 
-/** \file */
+/*!
+ * \file
+ *
+ * \defgroup UpnpString The UpnpString Class
+ *
+ * \author Marcelo Roberto Jimenez
+ *
+ * \version 1.0
+ *
+ * \brief Strings implementation in the UPnP library.
+ *
+ * This class implements basic string operations in the UPnP library.
+ *
+ * @{
+ */
 
 
 #ifdef __cplusplus
@@ -12,37 +26,105 @@ extern "C" {
 #endif /* __cplusplus */
 
 
-/** Type of the string objects inside libupnp. */
+/*!
+ * \brief Type of the string objects inside libupnp.
+ */
 typedef struct {} UpnpString;
 
 
-/** Constructor */
+/*!
+ * \brief Constructor.
+ *
+ * \return A pointer to a new allocated object.
+ */
 UpnpString *UpnpString_new();
 
-/** Destructor */
-void UpnpString_delete(UpnpString *p);
 
-/** Copy Constructor */
-UpnpString *UpnpString_dup(const UpnpString *p);
+/*!
+ * \brief Destructor.
+ */
+void UpnpString_delete(
+	/*! \em \b this pointer. */
+	UpnpString *p);
 
-/** Assignment operator */
-void UpnpString_assign(UpnpString *q, const UpnpString *p);
 
-/** The length of the string */
-int UpnpString_get_Length(const UpnpString *p);
+/*!
+ * \brief Copy Constructor.
+ *
+ * \return A pointer to a new allocated copy of the original object.
+ */
+UpnpString *UpnpString_dup(
+	/*! \em \b this pointer. */
+	const UpnpString *p);
 
-/** The pointer to char */
-const char *UpnpString_get_String(const UpnpString *p);
-void UpnpString_set_String(UpnpString *p, const char *s);
-void UpnpString_set_StringN(UpnpString *p, const char *s, int n);
 
-/* Clears the string, sets its size to zero */
-void UpnpString_clear(UpnpString *p);
+/*!
+ * \brief Assignment operator.
+ */
+void UpnpString_assign(
+	/*! \em \b this pointer. */
+	UpnpString *p,
+	/*! Pointer to the right hand side object. */
+	const UpnpString *q);
+
+
+/*!
+ * \brief Returns the length of the string.
+ *
+ * \return The length of the string.
+ * */
+int UpnpString_get_Length(
+	/*! \em \b this pointer. */
+	const UpnpString *p);
+
+
+/*!
+ * \brief Returns the pointer to char.
+ *
+ * \return The pointer to char.
+ */
+const char *UpnpString_get_String(
+	/*! \em \b this pointer. */
+	const UpnpString *p);
+
+
+/*!
+ * \brief Sets the string from a pointer to char.
+ */
+void UpnpString_set_String(
+	/*! \em \b this pointer. */
+	UpnpString *p,
+	/*! (char *) to copy from. */
+	const char *s);
+
+
+/*!
+ * \brief Sets the string from a pointer to char using a maximum of N chars.
+ */
+void UpnpString_set_StringN(
+	/*! \em \b this pointer. */
+	UpnpString *p,
+	/*! (char *) to copy from. */
+	const char *s,
+	/*! Maximum number of chars to copy.*/
+	int n);
+
+
+/*!
+ * \brief Clears the string, sets its size to zero.
+ */
+void UpnpString_clear(
+	/*! \em \b this pointer. */
+	UpnpString *p);
+
 
 #ifdef __cplusplus
 }
 #endif /* __cplusplus */
 
 
+/* @} UpnpString The UpnpString API */
+
+
 #endif /* STRING_H */
 

upnp/src/api/String.c

@@ -6,20 +6,30 @@
 #include "String.h"
 
 
-/* 
- * Due to its heavy use, this class is coded for efficiency, not for beauty.
- * Do not use this as example to other classes. Please take a look at any
- * other one.
- */
-
-
 #include <stdlib.h> // for calloc(), free()
 #include <string.h> // for strlen(), strdup()
 
 
+/*!
+ * \ingroup UpnpString
+ * 
+ * \brief Internal implementation of the class UpnpString.
+ *
+ * \internal
+ *
+ * Due to its heavy use, this class is coded for efficiency, not for beauty.
+ * Do not use this as example to other classes. Please take a look at any
+ * other one.
+ *
+ * \todo Always alloc a minimum size like 64 bytes or so and when shrinking
+ * do not perform a new memory allocation.
+ */
 struct SUpnpString
 {
+	/*! \brief Length of the string. */
 	int m_length;
+	/*! \brief Pointer to a dynamically allocated area that holds the NULL
+	 * terminated string. */
 	char *m_string;
 };
 
@@ -86,10 +96,10 @@ error_handler1:
 }
 
 
-void UpnpString_assign(UpnpString *q, const UpnpString *p)
+void UpnpString_assign(UpnpString *p, const UpnpString *q)
 {
-	if (q != p) {
-		UpnpString_set_String(q, UpnpString_get_String(p));
+	if (p != q) {
+		UpnpString_set_String(p, UpnpString_get_String(q));
 	}
 }