Coding-Conventions-and-Guidelines.md

@@ -103,12 +103,14 @@ Important rules, and notable differences are summarized here:
   class Beers;
   class Wine;
 
-  /* \class Bar
-   * \brief Just a very limited bar...  
+  /**
+   *  This is the doxygen description for the class Bar. 
+   *
+   * There can be extensive documentation added here
+   * spanning over many lines. 
    */
   class Bar 
   {
-   ///! trivial constructor
    Bar() = default; 
  
    ///! non-trivial constructor
@@ -117,16 +119,13 @@ Important rules, and notable differences are summarized here:
      wine_(wine)
      {}
  
-  ///! move constructor
   Bar( Bar && other) = delete;
 
-  ///! copy constructor
   Bar( Bar const& other):
     beer_(other.getBeer()),
     wine_(other.getWine())
     {} 
 
-  ///! assignment operator
   Bar& operator=( Bar const& other){
     if(this=&other) return *this;
     beer_ = other.getBeer();
@@ -134,7 +133,8 @@ Important rules, and notable differences are summarized here:
     return *this;
    } 
 
-   void DrinkAll(void);
+   ///! If you are very thirsty
+   void drinkAll(void);
 
    Beer getBeer() const {
       return beer_;
@@ -163,7 +163,6 @@ Important rules, and notable differences are summarized here:
       wine_=other;
     }
   
-  // data members last
   private:
     Beer beer_;
     Wine wine_;
@@ -269,7 +268,6 @@ Important rules, and notable differences are summarized here:
       1. https://en.cppreference.com/w/cpp/language/template_argument_deduction
       2. https://en.cppreference.com/w/cpp/language/class_template_argument_deduction
 
-
 ## General Rules
 
 - Basically never use "iostream" cout, cerr, and endl. We use our own logging machinery based on spdlog.
@@ -323,6 +321,70 @@ warning using the flag ```"FIXME"``` as keyword.
   ```
 
 
+
+## Doxygen Guidelines
+
+- please document all C++ symbols with doxygen. This is very natural and almost no additional effort. 
+- do not use necessary doxygen tags (most of them)
+- 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.
+- 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 ..."
+  ```
+  /** 
+    * This enum we need. 
+    * 
+    * Long description of enum and content.
+    */
+    enum class TheEnum { 
+      one  ///! special description for "one"
+    };
+
+  /** 
+    * This class handles that. 
+    * 
+    * Long description of class and functionality.
+    */
+    class TheClass {
+    public:
+      /**
+        * Function to make a complicated calculation.
+        *
+        * Eventually long description
+        */
+        return_type calculate(param1, param2, ...) const;
+    };
+  ```
+
+- 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. 
+  ```
+  /*! \file theFile.hpp
+   *  A brief description here.
+   * 
+   *  Details follow here.
+   */
+ 
+  /*! A macro that returns the maximum of \a a and \a b.
+   
+      Details.
+  */
+  #define MAX(a,b) (((a)>(b))?(a):(b))
+
+  /*! A close function.
+   * 
+   *  Details.
+   */
+  int close(int);
+  ```
+ 
+References:
+- https://www.rosettacommons.org/docs/latest/development_documentation/tutorials/doxygen-tips
+
+
 ## For components not coded in C++
 
  - fortran files end on ".f" ```sibyll23c.f```