STYLE: update documentation about central controlDict

bin/tools/foamCreateModuleInclude

@@ -219,7 +219,8 @@ echo "Using openfoam: $WM_PROJECT_DIR" 1>&2
 echo "==> $moduleOutput" 1>&2
 
 # Remove some cruft
-unset FOAM_JOB_DIR FOAM_RUN FOAM_SETTINGS FOAM_INST_DIR WM_PROJECT_INST_DIR
+unset FOAM_JOB_DIR FOAM_RUN FOAM_SETTINGS FOAM_CONTROLDICT
+unset FOAM_INST_DIR WM_PROJECT_INST_DIR
 unset WM_PROJECT_USER_DIR WM_THIRD_PARTY_DIR
 unset SCOTCH_VERSION
 

src/OpenFOAM/global/debug/debug.C

@@ -89,13 +89,14 @@ deleteControlDictPtr deleteControlDictPtr_;
 } // End namespace debug
 } // End namespace Foam
 
+
 // * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * * //
 
 Foam::dictionary& Foam::debug::controlDict()
 {
     if (!controlDictPtr_)
     {
-        string controlDictString(getEnv("FOAM_CONTROLDICT"));
+        string controlDictString(Foam::getEnv("FOAM_CONTROLDICT"));
         if (!controlDictString.empty())
         {
             // Read from environment

src/OpenFOAM/global/debug/debug.H

@@ -40,7 +40,7 @@ SourceFiles
 namespace Foam
 {
 
-// Forward declaration of classes
+// Forward declarations
 class dictionary;
 class Istream;
 class Ostream;
@@ -51,8 +51,18 @@ class simpleObjectRegistry;
 
 namespace debug
 {
-    //- The central control dictionary.
-    //  Located in ~/.OpenFOAM/VERSION or $WM_PROJECT_DIR/etc
+    //- The central control dictionary, the contents of which are either
+    //- taken directly from the FOAM_CONTROLDICT environment variable,
+    //- or generated by merging the contents of user/group/other files.
+    //
+    //  - ~/.OpenFOAM/{PROJECT_API}/controlDict
+    //  - ~/.OpenFOAM/controlDict
+    //  - $WM_PROJECT_SITE/{PROJECT_API}/etc/controlDict
+    //  - $WM_PROJECT_SITE/etc/controlDict
+    //  - $WM_PROJECT_DIR/etc/controlDict
+    //
+    //  Where {PROJECT_API} corresponds to the foamVersion::api value.
+    //
     //  \sa Foam::findEtcFile()
     dictionary& controlDict();