better description of the doxygen process (#1034)

* better description of the doxygen process

* better formatting

Author: couet

for_developers/doxygen/index.md

@@ -11,28 +11,30 @@ The ROOT team has adopted [Doxygen](https://www.doxygen.nl){:target="_blank"} fo
 the [Reference Guide](https://root.cern/doc/master/){:target="_blank"}. Here you will find a number of conventions
 and tips to be used in source code to generate proper documentation.
 
-## How to generate the doxygen documentation
-Developers may generate the documentation by hand to see the results of the current changes
-before committing them to the repository. The automatic daily Jenkins procedures will
-generate the complete set of documentation.
+## How to generate locally the doxygen documentation
+Developers can generate the documentation locally to review the results of their changes
+before committing them to the repository. The process is as follows:
 
 {% highlight sh %}
 $ cd <root_sources>/documentation/doxygen
 $ source <root_sources>/bin/thisroot.sh
 $ make
 {% endhighlight %}
 
-The results are placed by default at `${HOME}/rootdoc/html`.
-The script `$ROOTSYS/documentation/doxygen/makeinput.sh` defines the `INPUT` tag in `Doxyfile`.
-It can be edited to reduce the number of input files and thus reduce the time for generating
-the HTML pages. Typically you will keep only the folder(s) in which the documentation you are
-working on is. To see the result of this local build you should open, in your preferred web
-browser, the file `${HOME}/rootdoc/html/index.html`.
+By default, the results are located at `${HOME}/rootdoc/html`. This process will generate
+the full documentation, which may take several hours to complete! To minimize the generation
+time and preview only the changes you’ve made locally, edit the script
+`$ROOTSYS/documentation/doxygen/makeinput.sh` to limit the number of input files being scanned.
+Typically, you should keep only the folder(s) containing the documentation you are
+currently working on. To view the results of this local build, open the file
+`{HOME}/rootdoc/html/index.html` in your preferred web browser.
 
 ### Compilation prerequisites on Ubuntu
-- apt install doxygen make jupyter-nbconvert 
-- pip install scandir nbformat metakernel ipykernel
-- Optional: apt install qhelpgenerator-qt5. In case of older Ubuntu versions, use qt4-dev-tools instead, and modify in the Doxyfile QHG_LOCATION to /usr/lib/x86_64-linux-gnu/qt4/bin/qhelpgenerator
+- `apt install doxygen make jupyter-nbconvert`
+- `pip install scandir nbformat metakernel ipykernel`
+- Optional: `apt install qhelpgenerator-qt5`. In case of older Ubuntu versions, use `qt4-dev-tools`
+instead, and modify in the `Doxyfile` `QHG_LOCATION` to
+`/usr/lib/x86_64-linux-gnu/qt4/bin/qhelpgenerator`
 
 ## General Guidelines
 Classes and methods can be documented both in the .cxx and .h files. For the long descriptions
@@ -133,23 +135,23 @@ ROOT tutorials are also included in the ROOT documentation. The tutorials'
 macros headers should look like:
 
 {% highlight C++ %}
-\file
-\ingroup tutorial_hist
-\notebook
-Getting Contours From TH2D.
-
-#### Image produced by `.x ContourList.C`
-The contours values are drawn next to each contour.
-\macro_image
-
-#### Output produced by `.x ContourList.C`
-It shows that 6 contours and 12 graphs were found.
-\macro_output
-
-#### `ContourList.C`
-\macro_code
-
-\authors  Josh de Bever, Olivier Couet
+/// \file
+/// \ingroup tutorial_hist
+/// \notebook
+/// Getting Contours From TH2D.
+///
+/// #### Image produced by `.x ContourList.C`
+/// The contours' values are drawn next to each contour.
+/// \macro_image
+///
+/// #### Output produced by `.x ContourList.C`
+/// It shows that 6 contours and 12 graphs were found.
+/// \macro_output
+///
+/// #### `ContourList.C`
+/// \macro_code
+///
+/// \authors  Josh de Bever, Olivier Couet
 {% endhighlight %}
 
 This example shows that four new directives have been implemented: