Coding-Conventions-and-Guidelines.md

@@ -310,7 +310,7 @@ warning using the flag ```"FIXME"``` as keyword.
   and not 
   ```
   /**
-    * Here we have a length comment on the purpose of this function TimeOfIntersection to explain that
+    * Here we have a long comment on the purpose of this function TimeOfIntersection to explain that
     * it calculated the "time of intersection" and all the strange symbols and conventions used here. 
     * Such a comment only bloats the code, and provides no further information compared to the code above. 
   **/
@@ -332,14 +332,14 @@ warning using the flag ```"FIXME"``` as keyword.
 - a doxygen comment block has to be initiated by "/**", "///!", or "/*!"
 - doxygen tags start with either "@" or "\"
 - doxygen comment blocks are automatically always for the next (directly following) symbol. This can be a class/struct/function/variable/enum/namespace/etc.
-- thus, never specify "\class XY" if it is anyway not needed.
-- the single separated first line of a document block is the "brief" description (thus, do not use \brief)
-- a comment block can be as long as needed and benefit from very rich formatting, including math, verbatim, etc.
+- thus, never specify "\class XY", "\function xxxY", etc. since it is typically not needed.
+- the single separated first line of a document block is the "brief" description (thus, also do not use "\brief blah...")
+- a comment block can be as long as needed and benefit from very rich formatting, including math (via "\f$ latex-here \f$"), verbatim, etc.
 - the extra tags we might want to use, if applicable and useful, are "\param ...", "\return ...", 
-- very useful may be: "\sa ..." (see also), "\example ...", "\todo ...", "\bug ..."
+- very useful may be: "\sa ..." (see also), "\ref", "\example ...", "\todo ...", "\bug ..."
   ```
   /** 
-    * This enum we need. 
+    * This enum we need (brief). 
     * 
     * Long description of enum and content.
     */
@@ -348,7 +348,7 @@ warning using the flag ```"FIXME"``` as keyword.
     };
 
   /** 
-    * This class handles that. 
+    * This class handles that...briefly. 
     * 
     * Long description of class and functionality.
     */
@@ -363,12 +363,9 @@ warning using the flag ```"FIXME"``` as keyword.
     };
   ```
 
-- special note: only, if you need to describe global variables/enums or free functions, you must add a block "\file ..." to describe the file, too. Never do this otherwise. 
+- special note: only, if you need to describe global variables/enums or free functions, you must add a block "\file ..." to describe the file, too. Never add "\file .." otherwise, it is useless. 
   ```
   /*! \file theFile.hpp
-   *  A brief description here.
-   * 
-   *  Details follow here.
    */
  
   /*! A macro that returns the maximum of \a a and \a b.
@@ -383,6 +380,19 @@ warning using the flag ```"FIXME"``` as keyword.
    */
   int close(int);
   ```
+- if you want to group class members use "\{" and "\}":
+   ```
+    /**
+     * \name Very brief description
+     * Longer explanation, details. 
+     * \{
+     **/
+    /// eventual description of member1
+    int member1();
+    /// eventual description of member2
+    void member2(int a, double b) const;
+    /** \} */
+   ```
  
 References:
 - https://www.rosettacommons.org/docs/latest/development_documentation/tutorials/doxygen-tips