diff --git a/Doxyfile b/Doxyfile index 8f10df3..39d1a11 100644 --- a/Doxyfile +++ b/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 diff --git a/upnp/inc/String.h b/upnp/inc/String.h index a64dc2d..9454b81 100644 --- a/upnp/inc/String.h +++ b/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 */ diff --git a/upnp/src/api/String.c b/upnp/src/api/String.c index eb5efc0..e87dbff 100644 --- a/upnp/src/api/String.c +++ b/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 // for calloc(), free() #include // 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)); } }