Update doc guidelines (#1200)

Author: couet

for_developers/docs/guidelines.md

@@ -11,23 +11,19 @@ Classes and methods can be documented both in the .cxx and .h files. For the lon
 of a class functionality and its methods we usually prefer the .cxx file.
 
 ## Class documentation
-The documentation for the class is in general located at the beginning of the .cxx file.
-The `\class` Doxygen command is mandatory otherwise Doxygen will not associate the comments
-to the proper class.  The first sentence is a brief description of the class and will
-appear in all class listings. For an example see the TF2 class documentation:
+The class documentation is generally placed at the beginning of the .cxx file. The `\class`
+Doxygen command is mandatory; otherwise, Doxygen will not associate the comments with the
+correct class. The first sentence or the line starting with `\brief` provides a short
+description of the class, as it will appear in all class listings. The `\ingroup` directive
+specifies in which group of classes the class belongs. For an example, see
+[the documentation of the TF2 class](https://root.cern/doc/master/classTF2.html).
 
 {% highlight C++ %}
 /** \class TF2
-A 2-Dim function with parameters
+\ingroup Functions
+\brief A 2-Dim function with parameters.
 
 TF2 graphics function is via the TH1 drawing functions.
-Example of a function
-
-    TF2 *f2 = new TF2("f2","sin(x)*sin(y)/(x*y)",0,5,0,5);
-    f2->Draw();
-
-\image html tf2_function2.png
-See TF1 class for the list of functions formats
 */
 {% endhighlight %}
 
@@ -101,17 +97,17 @@ The usage of "//!" will still result in transiency of members but not in Doxygen
 
 ## Tutorials' documentation
 
-ROOT tutorials are also included in the ROOT documentation. The tutorials'
-macros headers should look like:
+ROOT tutorials are also part of the ROOT documentation. The macro headers for C++ tutorials
+(see the note about Python tutorials) should follow this format:
 
 {% highlight C++ %}
 /// \file
 /// \ingroup tutorial_hist
 /// \notebook
-/// Getting Contours From TH2D.
+/// \preview Getting Contours From TH2D.
 ///
 /// #### Image produced by `.x ContourList.C`
-/// The contours' values are drawn next to each contour.
+/// The contours values are drawn next to each contour.
 /// \macro_image
 ///
 /// #### Output produced by `.x ContourList.C`
@@ -121,18 +117,19 @@ macros headers should look like:
 /// #### `ContourList.C`
 /// \macro_code
 ///
+/// \date November 2022
 /// \authors  Josh de Bever, Olivier Couet
 {% endhighlight %}
 
-This example shows that four new directives have been implemented:
+This example shows that five ROOT tutorials' specific directives are available:
 
  1. `\macro_image`
  The images produced by this macro are shown. A caption can be added to document
  the pictures: `\macro_image This is a picture`. When the option `(nobatch)`
  is passed, the macro is executed without the batch option.
  Some tutorials generate pictures (png or pdf) with `Print` or `SaveAs`.
  Such pictures can be displayed with `\macro_image (picture_name.png[.pdf])`
- When the option (tcanvas_js) is used the image is displayed as JavaScript.
+ When the option (tcanvas_js) is used [the image is displayed as JavaScript](https://root.cern/doc/master/arrows_8C.html).
  For ROOT 7 tutorials, when the option (rcanvas_js) is used the image is displayed as json file.
 
  2. `\macro_code`
@@ -148,6 +145,14 @@ This example shows that four new directives have been implemented:
  This directive needs [jupyter to be properly installed](https://jupyter.org/install) when
  building the documentation of tutorials having this directive.
 
+5. `\preview`
+ To display the first image generated by the tutorial as an
+ [icon in the list of tutorials](https://root.cern/doc/master/group__tutorial__graphics.html).
+
 
-Note that the doxygen directive `\authors` or `\author` must be the last one
+### Notes
+
+- The doxygen directive `\authors` or `\author` *must be* the last one
 of the macro header.
+
+- In python tutorials the comments for the header must be "`##`" ("`#`" will produce an empty page).