[ci skip] Minor changes to comments and dev documentation.

Author: c-lipka

source-doc/compiler.md

@@ -1,7 +1,8 @@
 # Compiler Requirements {#compiler}
 
 
-@section exot   General Presumptions
+General Presumptions {#compiler_exot}
+====================
 
 While POV-Ray is being developed with portability high in mind, the C++ standard allows for some degrees of freedom that
 we consider too exotic to cater to. We therefore presume all compilers and runtime environments to adhere to the
@@ -18,10 +19,11 @@ following additional restrictions:
     separator, in include directives.
 
   - **Integer Division**: Integer division is presumed to round towards zero. This also implies that the remainder (as
-    computed by the modulus operator '%') is negative (or zero) if the dividend and divisor have different sign.
+    computed by the modulus operator `%`) is negative (or zero) if the dividend and divisor have different sign.
 
 
-@section povms  POVMS Additional Restrictions
+POVMS Additional Restrictions {#compiler_povms}
+=============================
 
 To support network rendering (a feature not yet implemented but planned) in a heterogenous network, the POVMS interface
 imposes the following additional restriction on the compiler:

source-doc/styleguide.md

@@ -50,7 +50,7 @@ Even pure cosmetics can have a significant impact on how easily code can be read
 In the POV-Ray project, we are using the following formatting style for new code, and are in the process of
 transitioning existing code to these coventions:
 
-  - Indentation follows Allman style, with an indent of 4 spaces (no tabs), e.g.:
+  - Indentation of braces follows Allman style, with an indent of 4 spaces (no tabs), e.g.:
 
         while (x == y)
         {
@@ -233,6 +233,8 @@ source code with comments.
 The interface provided by any source file should be documented in the respective header file, using
 a format compatible with Doxygen 1.8.8. For consistency, please use JavaDoc-style comments (`/// ...`
 or `/** ... */`; the general rules for comments apply) and JavaDoc-style tags (`@``foo`).
+C++ single-line style comments should be preferred, as block comments may occasionally interfere with
+Doxygen's Markdown support.
 
 @note   Platform-specific modules may mandate a different tag style, such as (hypothetically) DocXML
         style for the Windows GUI modules.
@@ -254,6 +256,8 @@ following guidelines:
   - **Attention**: Use the `@``attention` tag when documenting pitfalls that may come as a big surprise to the reader or
     have grave effects when not avoided.
 
+However, always use the following instead if they are appropriate:
+
   - **To-Do**: Use the `@``todo` tag when documenting that something is still unfinished and needs more work.
   - **Deprecated**: Use the `@``deprecated` tag when documenting that somehting is only kept around for backward
     compatibility and should no longer be used in new code.

source/base/version.h

@@ -45,7 +45,7 @@
 #define OFFICIAL_VERSION_STRING "3.7.1"
 #define OFFICIAL_VERSION_NUMBER 371
 
-#define POV_RAY_PRERELEASE "alpha.8698543"
+#define POV_RAY_PRERELEASE "alpha.8701451"
 
 #if (POV_RAY_IS_AUTOBUILD == 1) && ((POV_RAY_IS_OFFICIAL == 1) || (POV_RAY_IS_SEMI_OFFICIAL == 1))
 #ifdef POV_RAY_PRERELEASE

source/core/configcore.h

@@ -66,7 +66,7 @@ namespace pov
 #endif
 
 #ifndef LIGHT_INTERSECTION_VECTOR_SIZE
-#define LIGHT_INTERSECTION_VECTOR_SIZE  512
+#define LIGHT_INTERSECTION_VECTOR_SIZE  512 // TODO - I think this should be LIGHTSOURCE_VECTOR_SIZE*2 [CLi]
 #endif
 
 #ifndef LIGHTSOURCE_VECTOR_SIZE

source/parser/parser.cpp

@@ -3315,6 +3315,7 @@ ObjectPtr Parser::Parse_Light_Source ()
             Parse_Begin();
             EXPECT
 #ifdef GLOBAL_PHOTONS
+                // TODO -- if we ever revive this, we need to choose a different keyword for this
                 CASE(GLOBAL_TOKEN)
                     Object->Ph_Density = Allow_Float(1.0);
                     if (Object->Ph_Density > 0)
@@ -7136,6 +7137,7 @@ void Parser::Parse_Global_Settings()
                 END_CASE
 
 #ifdef GLOBAL_PHOTONS
+                // TODO -- if we ever revive this, we need to choose a different keyword for this
                 CASE(GLOBAL_TOKEN)
                     sceneData->photonSettings.globalCount = (int)Parse_Float();
                 END_CASE

unix/VERSION

@@ -1 +1 @@
-3.7.1-alpha.8698543
+3.7.1-alpha.8701451