[PATCH] Fix Doxygen group comments

classic Classic list List threaded Threaded
2 messages Options
Reply | Threaded
Open this post in threaded view
|

[PATCH] Fix Doxygen group comments

Marcel Gosselin
Here is a patch that fixes some Doxygen usage. The comments that used
the following form
    /** @{ */
    /** Here is some text that will not be displayed or displayed at the
wrong place */
    void fct1();
    void fct2();
    /** @} */
gave the wrong display. Some documentation was hidden because the
parsing of some of these tags
did not give the expected result.

The right way to do this is like this
   /** @name Group name
         My brief description

         Longer description.

         @note Some note
   */
   /** @{ */

The @{ can be in the same /** */ as the previous info but it needs to be
at the end and either a @name or @defgroup should appear before it.

Here is the log message
[[[
Improve Doxygen group usage by placing the "@{" just before the first
element of the
group and by adding an "@name" group name.

* subversion\include\svn_fs.h
* subversion\include\svn_dav.h
* subversion\include\svn_subst.h
* subversion\include\svn_config.h
* subversion\include\svn_client.h
* subversion\include\svn_auth.h
  Move the "@{" group tags and add "@name" to those groups.
]]]

Index: subversion/include/svn_fs.h
===================================================================
--- subversion/include/svn_fs.h (revision 14950)
+++ subversion/include/svn_fs.h (working copy)
@@ -52,8 +52,9 @@
 typedef struct svn_fs_t svn_fs_t;
 
 
-/** @{
- * Filesystem configuration options
+/**
+ * @name Filesystem configuration options
+ * @{
  */
 #define SVN_FS_CONFIG_BDB_TXN_NOSYNC            "bdb-txn-nosync"
 #define SVN_FS_CONFIG_BDB_LOG_AUTOREMOVE        "bdb-log-autoremove"
Index: subversion/include/svn_dav.h
===================================================================
--- subversion/include/svn_dav.h (revision 14950)
+++ subversion/include/svn_dav.h (working copy)
@@ -49,8 +49,11 @@
  */
 #define SVN_DAV_OPTIONS_HEADER "X-SVN-Options"
 
-/** @{
- * Specific options that can appear in the options-header: */
+/**
+ * @name options-header defines
+ * Specific options that can appear in the options-header:
+ * @{
+ */
 #define SVN_DAV_OPTION_NO_MERGE_RESPONSE "no-merge-response"
 #define SVN_DAV_OPTION_LOCK_BREAK        "lock-break"
 #define SVN_DAV_OPTION_LOCK_STEAL        "lock-steal"
@@ -79,7 +82,9 @@
 #define SVN_DAV_LOCK_OWNER_HEADER "X-SVN-Lock-Owner"
 
 
-/** @{
+/**
+ * @name Fulltext MD5 headers
+ *
  * These headers are for client and server to verify that the base
  * and the result of a change transmission are the same on both
  * sides, regardless of what transformations (svndiff deltification,
@@ -96,6 +101,7 @@
  * corrupt, the error will be caught earlier if the base md5 is used.
  *
  * Normal WebDAV or DeltaV clients don't use these.
+ * @{
  */
 #define SVN_DAV_BASE_FULLTEXT_MD5_HEADER "X-SVN-Base-Fulltext-MD5"
 #define SVN_DAV_RESULT_FULLTEXT_MD5_HEADER "X-SVN-Result-Fulltext-MD5"
Index: subversion/include/svn_subst.h
===================================================================
--- subversion/include/svn_subst.h (revision 14950)
+++ subversion/include/svn_subst.h (working copy)
@@ -78,9 +78,12 @@
 /** Values used in keyword expansion. */
 typedef struct svn_subst_keywords_t
 {
-  /** @{ */
-  /** String expansion of the like-named keyword, or NULL if the keyword
-   * was not selected in the svn:keywords property. */
+  /**
+   * @name svn_subst_keywords_t fields
+   * String expansion of the like-named keyword, or NULL if the keyword
+   * was not selected in the svn:keywords property.
+   * @{
+   */
   const svn_string_t *revision;
   const svn_string_t *date;
   const svn_string_t *author;
Index: subversion/include/svn_config.h
===================================================================
--- subversion/include/svn_config.h (revision 14950)
+++ subversion/include/svn_config.h (working copy)
@@ -50,9 +50,11 @@
 
 /*** Configuration Defines ***/
 
-/** @{
+/**
+ * @name Client configuration files strings
  * Strings for the names of files, sections, and options in the
  * client configuration files.
+ * @{
  */
 #define SVN_CONFIG_CATEGORY_SERVERS        "servers"
 #define SVN_CONFIG_SECTION_GROUPS               "groups"
@@ -90,9 +92,10 @@
 #define SVN_CONFIG_SECTION_AUTO_PROPS           "auto-props"
 /** @} */
 
-/** @{
+/** @name Repository conf directory configuration files strings
  * Strings for the names of sections and options in the
  * repository conf directory configuration files.
+ * @{
  */
 /* For repository svnserve.conf files */
 #define SVN_CONFIG_SECTION_GENERAL              "general"
Index: subversion/include/svn_client.h
===================================================================
--- subversion/include/svn_client.h (revision 14950)
+++ subversion/include/svn_client.h (working copy)
@@ -278,11 +278,12 @@
 } svn_client_commit_info_t;
 
 
-/** @{
- * State flags for use with the @c svn_client_commit_item_t structure
- *
+/**
+ * @name Commit state flags
+ * @brief State flags for use with the @c svn_client_commit_item_t structure
  * (see the note about the namespace for that structure, which also
  * applies to these flags).
+ * @{
  */
 #define SVN_CLIENT_COMMIT_ITEM_ADD         0x01
 #define SVN_CLIENT_COMMIT_ITEM_DELETE      0x02
@@ -425,12 +426,15 @@
 } svn_client_ctx_t;
 
 
-/** @{
+/**
+ * @name Authentication information file names
+ *
  * Names of files that contain authentication information.
  *
  * These filenames are decided by libsvn_client, since this library
  * implements all the auth-protocols;  libsvn_wc does nothing but
  * blindly store and retrieve these files from protected areas.
+ * @{
  */
 #define SVN_CLIENT_AUTH_USERNAME            "username"
 #define SVN_CLIENT_AUTH_PASSWORD            "password"
@@ -1967,9 +1971,12 @@
   /** Whether or not to ignore the next 10 wc-specific fields. */
   svn_boolean_t has_wc_info;
 
-  /** @{ */
-  /** These things only apply to a working-copy path.
-   * See svn_wc_entry_t for explanations. */
+  /**
+   * @name Working-copy path fields
+   * These things only apply to a working-copy path.
+   * See svn_wc_entry_t for explanations.
+   * @{
+   */
   svn_wc_schedule_t schedule;
   const char *copyfrom_url;
   svn_revnum_t copyfrom_rev;
Index: subversion/include/svn_auth.h
===================================================================
--- subversion/include/svn_auth.h (revision 14950)
+++ subversion/include/svn_auth.h (working copy)
@@ -494,10 +494,12 @@
 /** The auth-hash prefix indicating that the parameter is global. */
 #define SVN_AUTH_PARAM_PREFIX "svn:auth:"
 
-/** @{ */
-/** @brief Any 'default' credentials that came in through the application
- * itself, (e.g. --username and --password options).  Property values are
- * const char *.  */
+/**
+ * @name Default credentials defines
+ * Any 'default' credentials that came in through the application itself,
+ * (e.g. --username and --password options). Property values are
+ * const char *.
+ * @{ */
 #define SVN_AUTH_PARAM_DEFAULT_USERNAME  SVN_AUTH_PARAM_PREFIX "username"
 #define SVN_AUTH_PARAM_DEFAULT_PASSWORD  SVN_AUTH_PARAM_PREFIX "password"
 /** @} */


---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]
Reply | Threaded
Open this post in threaded view
|

Re: [PATCH] Fix Doxygen group comments

Brian W. Fitzpatrick

On Jun 2, 2005, at 10:17 PM, Marcel Gosselin wrote:

> Improve Doxygen group usage by placing the "@{" just before the  
> first element of the
> group and by adding an "@name" group name.
>
> * subversion\include\svn_fs.h
> * subversion\include\svn_dav.h
> * subversion\include\svn_subst.h
> * subversion\include\svn_config.h
> * subversion\include\svn_client.h
> * subversion\include\svn_auth.h
>  Move the "@{" group tags and add "@name" to those groups.

Applied in r14951.

Thanks again!

-Fitz

---------------------------------------------------------------------
To unsubscribe, e-mail: [hidden email]
For additional commands, e-mail: [hidden email]