From 201554e9c0abd15b90bf14da3ed13d351a46165f Mon Sep 17 00:00:00 2001
From: Andre Sailer <andre.philippe.sailer@cern.ch>
Date: Fri, 22 Jan 2016 16:32:57 +0000
Subject: [PATCH] Plugin documentation draft

Add DDRec/src/plugins to folders documented by doxygen

Add groups for plugins and some example
Add an entry in the main "Modules" part of the doxygen website so they are easily found.
And sub groups for different plugin types.
See changes in the plugins for example. The documentation in these changes is not complete.
---
 DDG4/lcio/LCIOFileReader.cpp               | 12 +++++++++++
 DDG4/plugins/Geant4DefaultRangeCut.cpp     | 14 +++++++++++++
 DDG4/plugins/Geant4ExtraParticles.cpp      | 13 ++++++++++++
 DDRec/src/plugins/createSurfaceManager.cpp | 23 +++++++++++++++-------
 cmake/Doxyfile.in                          |  1 +
 doc/doxygen/DD4hepGroups.h                 | 23 ++++++++++++++++++++++
 6 files changed, 79 insertions(+), 7 deletions(-)

diff --git a/DDG4/lcio/LCIOFileReader.cpp b/DDG4/lcio/LCIOFileReader.cpp
index d75dbb154..4b0cc1abb 100644
--- a/DDG4/lcio/LCIOFileReader.cpp
+++ b/DDG4/lcio/LCIOFileReader.cpp
@@ -11,6 +11,18 @@
 // Author     : M.Frank
 //
 //==========================================================================
+
+/** \addtogroup Geant4EventReader
+ *
+ @{
+  \package LCIOFileReader
+ * \brief Plugin to read lcio files
+ *
+ And here we can put a longer description, parameters, examples...
+ *
+@}
+ */
+
 #ifndef DD4HEP_DDG4_LCIOFILEREADER_H
 #define DD4HEP_DDG4_LCIOFILEREADER_H
 
diff --git a/DDG4/plugins/Geant4DefaultRangeCut.cpp b/DDG4/plugins/Geant4DefaultRangeCut.cpp
index 016ef1381..4027ad2cb 100644
--- a/DDG4/plugins/Geant4DefaultRangeCut.cpp
+++ b/DDG4/plugins/Geant4DefaultRangeCut.cpp
@@ -11,6 +11,20 @@
 // Author     : M.Frank
 //
 //==========================================================================
+
+/** \addtogroup Geant4PhysicsConstructor
+ *
+ * @{
+ * \package Geant4RangeCut
+ *
+ * \brief PhysicsConstructor to change the global range cut
+
+ This plugin allows one to change the global geant4 range cut for producing secondaries.
+
+ *
+ * @}
+ */
+
 #ifndef DDG4_Geant4DefaultRangeCut_h
 #define DDG4_Geant4DefaultRangeCut_h 1
 
diff --git a/DDG4/plugins/Geant4ExtraParticles.cpp b/DDG4/plugins/Geant4ExtraParticles.cpp
index 1ca529240..3387fe5af 100644
--- a/DDG4/plugins/Geant4ExtraParticles.cpp
+++ b/DDG4/plugins/Geant4ExtraParticles.cpp
@@ -6,6 +6,19 @@
 // $Id$
 // $Name: $
 
+/** \addtogroup Geant4PhysicsConstructor
+ *
+ * @{
+ * \package Geant4ExtraParticles
+ *
+ * \brief PhysicsConstructor to add additional particles to geant
+
+ When enabled this constructor will read a particle.tbl file and add all particles in it to the geant4 particle table.
+ This can be used to let geant know about some B-baryons with non-zero lifetime for example.
+ *
+ * @}
+ */
+
 #include "Geant4ExtraParticles.h"
 #include "DDG4/Geant4PhysicsConstructor.h"
 #include "DDG4/Geant4Kernel.h"
diff --git a/DDRec/src/plugins/createSurfaceManager.cpp b/DDRec/src/plugins/createSurfaceManager.cpp
index a6fcf406c..f6793aa76 100644
--- a/DDRec/src/plugins/createSurfaceManager.cpp
+++ b/DDRec/src/plugins/createSurfaceManager.cpp
@@ -9,13 +9,22 @@ namespace DD4hep{
     
     using namespace Geometry ;
 
-    /** Plugin that creates a SurfaceManager object and attaches
-     *  it to lcdd as a user extension object.
-     * 
-     *  @author  F.Gaede, CERN/DESY
-     *  @date May, 11 2015
-     *  @version $Id: $
-     */
+
+    /**
+    \addtogroup SurfacePlugin
+    @{
+    \package SurfaceManager
+
+    *  \brief Plugin that creates a SurfaceManager object and attaches it to lcdd as a user extension object.
+    *
+    @}
+    *
+    *  @author  F.Gaede, CERN/DESY
+    *  @date May, 11 2015
+    *  @version $Id: $
+    */
+
+
     static long createSurfaceManager(LCDD& lcdd, int /*argc*/, char** /*argv*/) {
 
       printout(INFO,"InstallSurfaceManager","**** running plugin InstallSurfaceManager ! " );
diff --git a/cmake/Doxyfile.in b/cmake/Doxyfile.in
index 5aa6e2815..91d4315e7 100644
--- a/cmake/Doxyfile.in
+++ b/cmake/Doxyfile.in
@@ -670,6 +670,7 @@ INPUT += @CMAKE_CURRENT_SOURCE_DIR@/DDSegmentation/src
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/DDSegmentation/include/DDSegmentation
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/DDRec/src
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/DDRec/src/gear
+INPUT += @CMAKE_CURRENT_SOURCE_DIR@/DDRec/src/plugins
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/DDRec/include/DDRec
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/DDRec/include/DDRec/API
 INPUT += @CMAKE_CURRENT_SOURCE_DIR@/DDRec/include/DDRec/Extensions
diff --git a/doc/doxygen/DD4hepGroups.h b/doc/doxygen/DD4hepGroups.h
index 41f9bcce6..939a97110 100644
--- a/doc/doxygen/DD4hepGroups.h
+++ b/doc/doxygen/DD4hepGroups.h
@@ -83,3 +83,26 @@ namespace UTIL {}
 
 
 /**@}*/
+
+
+/// Plugins of all kinds and purposes
+/**
+ *  \defgroup Plugins
+ *  @{
+
+ *  \defgroup Geant4ActionPlugin
+ \brief Plugins that are a Geant4Actions
+
+ *  \defgroup SurfacePlugin
+ \brief Plugins to manipulate surfaces automatically
+
+ *  \defgroup Geant4EventReader
+ \brief InputFile Reader Plugins
+
+ *  \defgroup Geant4SDActionPlugin
+ \brief Sensitive Detector Implementations
+
+ *  \defgroup Geant4PhysicsConstructor
+ \brief Extensions for PhysicsLists
+
+ @}*/
-- 
GitLab