Update various comments and a few text strings.

appveyor.yml

@@ -80,7 +80,7 @@ for:
       $env:pov_release_type = ($env:pov_build_type).ToLower() + ' release'
       $env:pov_build_title = $env:pov_build_type + ' build'
       $env:pov_build_message += '**Note:** This is a binary-only ' + $env:pov_release_type + '; to install, copy the '
-      $env:pov_build_message += 'binary into an existing POV-Ray 3.7 installation. (Make sure to backup the original '
+      $env:pov_build_message += 'binary into an existing POV-Ray v3.7 installation. (Make sure to backup the original '
       $env:pov_build_message += 'binary first.)'
       $env:pov_build_message += "`n`n"
       $env:pov_build_message += 'These binaries require Windows Vista or higher, due to limitations of our automated '

source/core/lighting/photons.cpp

@@ -2641,7 +2641,7 @@ void LightTargetCombo::computeAnglesAndDeltas(shared_ptr<SceneData> sceneData)
     if(light->Parallel)
     {
         // OK, here we fake things a bit for parallel lights.  Theta is not really theta.
-        // It really represents the radius... but why re-code an entire loop.  For POV 4.0
+        // It really represents the radius... but why re-code an entire loop.  For POV-Ray v4.0
         // this should be re-written as an abstract class with polymorphism.
         dtheta = photonSpread;
     }

source/core/material/pattern.cpp

@@ -14,7 +14,7 @@
 /// ----------------------------------------------------------------------------
 ///
 /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
-/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
 ///
 /// POV-Ray is free software: you can redistribute it and/or modify
 /// it under the terms of the GNU Affero General Public License as
@@ -6525,7 +6525,7 @@ DBL HexagonPattern::Evaluate(const Vector3d& EPoint, const Intersection *pIsecti
 
     /* Avoid mirroring across x-axis. */
 
-    z = z < 0.0 ? 5.196152424 - fabs(z) : z;
+    z = z < 0.0 ? 5.196152424 - fabs(z) : z;    /// TODO FIXME - magic number! Use an aptly named const instead.
 
     /* Scale point to make calcs easier. */
 
@@ -8201,7 +8201,7 @@ DBL RipplesPattern::EvaluateRaw(const Vector3d& EPoint, const Intersection *pIse
 *
 * RETURNS
 *
-*   DBL value in the range 0.0 to 1.0, 0.0 if normal is NULL
+*   DBL value in the range 0.0 to 1.0, 0.0 if intersection struct is `nullptr`
 *
 * AUTHOR
 *
@@ -8271,15 +8271,15 @@ DBL SlopePattern::EvaluateRaw(const Vector3d& EPoint, const Intersection *pIsect
         return value1; /* no altitude defined */
     }
 
-    /* Calculate projection of Epoint along altitude vector */
+    /* Calculate projection of EPoint along altitude vector */
     if (altitudeAxis > 0)
         /* short case 1: altitude vector in x, y or z direction */
         value2 = EPoint[altitudeAxis - 1];
     else if (altitudeAxis < 0)
         /* short case 2: altitude vector in negative x, y or z direction */
         value2 = -EPoint[-altitudeAxis - 1];
     else
-        /* projection of Epoint along altitude vector */
+        /* projection of EPoint along altitude vector */
         value2 = dot(EPoint, altitudeDirection);
 
     if (0.0 != altitudeModWidth)

source/core/math/polynomialsolver.cpp

@@ -10,7 +10,7 @@
 /// @parblock
 ///
 /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
-/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
 ///
 /// POV-Ray is free software: you can redistribute it and/or modify
 /// it under the terms of the GNU Affero General Public License as
@@ -1056,7 +1056,7 @@ static int difficult_coeffs(int n, DBL *x)
 * DESCRIPTION
 *
 *   Test to see if any coeffs are more than 6 orders of magnitude
-*   larger than the smallest (function from POV 1.0) [DB 8/94].
+*   larger than the smallest (function from POV-Ray v1.0) [DB 8/94].
 *
 * CHANGES
 *
@@ -1555,7 +1555,7 @@ static int polysolve(int order, const DBL *Coeffs, DBL *roots)
 *
 *   WARNING: This function can only be used for polynomials if small roots
 *   (i.e. |x| < epsilon) are not needed. This is the case for ray/object
-*   intersection tests because only intersecions with t > 0 are valid.
+*   intersection tests because only intersections with t > 0 are valid.
 *
 *   NOTE: Only one root at x = 0 will be eliminated.
 *

source/core/math/quaternion.cpp

@@ -5,13 +5,13 @@
 /// Implementation of Quaternion algebra julia fractals.
 ///
 /// @author Pascal Massimino (original code)
-/// @author Tim Wegner (revisions and updates for POV-Ray 3.x)
+/// @author Tim Wegner (revisions and updates for POV-Ray v3.x)
 ///
 /// @copyright
 /// @parblock
 ///
 /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
-/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
 ///
 /// POV-Ray is free software: you can redistribute it and/or modify
 /// it under the terms of the GNU Affero General Public License as

source/core/render/trace.cpp

@@ -8,7 +8,7 @@
 /// @parblock
 ///
 /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
-/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
 ///
 /// POV-Ray is free software: you can redistribute it and/or modify
 /// it under the terms of the GNU Affero General Public License as
@@ -622,6 +622,11 @@ void Trace::ComputeOneTextureColour(MathColour& resultColour, ColourChannel& res
                 ComputeAverageTextureColours(resultColour, resultTransm, texture, warps, tpoint, rawnormal, ray, weight, isect, shadowflag, photonPass);
                 break;
             case UV_MAP_PATTERN:
+                // TODO FIXME
+                //  I think we have a serious problem here regarding bump mapping:
+                //  The UV vector doesn't contain any information about the (local) *orientation* of U and V in our XYZ co-ordinate system!
+                //  This causes slopes do be applied in the wrong directions.
+
                 // Don't bother warping, simply get the UV vect of the intersection
                 isect.Object->UVCoord(uvcoords, &isect, threadData);
                 tpoint = Vector3d(uvcoords[U], uvcoords[V], 0.0);
@@ -2334,6 +2339,11 @@ void Trace::ComputeShadowColour(const LightSource &lightsource, Intersection& is
     // now switch to UV mapping if we need to
     if(Test_Flag(isect.Object, UV_FLAG))
     {
+        // TODO FIXME
+        //  I think we have a serious problem here regarding bump mapping:
+        //  The UV vector doesn't contain any information about the (local) *orientation* of U and V in our XYZ co-ordinate system!
+        //  This causes slopes do be applied in the wrong directions.
+
         // get the UV vect of the intersection
         isect.Object->UVCoord(uv_Coords, &isect, threadData);
         // save the normal and UV coords into Intersection

source/core/render/tracepixel.cpp

@@ -13,7 +13,7 @@
 /// @parblock
 ///
 /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
-/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
 ///
 /// POV-Ray is free software: you can redistribute it and/or modify
 /// it under the terms of the GNU Affero General Public License as
@@ -1280,7 +1280,7 @@ TracePixel::FocalBlurData::FocalBlurData(const Camera& camera, TraceThreadData*
         }
     }
 
-    // Calculate vectors perpendicular to the current ray
+    // Calculate vectors perpendicular to the optical axis
     // We're making a "+" (crosshair) on the film plane.
 
     // XPerp = vector perpendicular to y/z plane

source/core/scene/object.h

@@ -10,7 +10,7 @@
 /// @parblock
 ///
 /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
-/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
 ///
 /// POV-Ray is free software: you can redistribute it and/or modify
 /// it under the terms of the GNU Affero General Public License as
@@ -95,7 +95,7 @@ namespace pov
 #define HIERARCHY_FLAG            0x00000400L ///< Object can have a bounding hierarchy.
 #define HOLLOW_FLAG               0x00000800L ///< Object is hollow (atmosphere inside).
 #define HOLLOW_SET_FLAG           0x00001000L ///< Hollow explicitly set in scene file.
-#define UV_FLAG                   0x00002000L ///< Object uses UV mapping.
+#define UV_FLAG                   0x00002000L ///< Object uses UV mapping. Set if `uv_mapping` is specified on an object itself.
 #define DOUBLE_ILLUMINATE_FLAG    0x00004000L ///< Illuminate both sides of the surface.
 #define NO_IMAGE_FLAG             0x00008000L ///< Object doesn't catch camera rays.
 #define NO_REFLECTION_FLAG        0x00010000L ///< Object doesn't catch reflection rays.

source/core/shape/csg.cpp

@@ -8,7 +8,7 @@
 /// @parblock
 ///
 /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
-/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
 ///
 /// POV-Ray is free software: you can redistribute it and/or modify
 /// it under the terms of the GNU Affero General Public License as
@@ -66,7 +66,7 @@ namespace pov
 inline bool Test_Ray_Flags(const Ray& ray, ConstObjectPtr obj)
 {
     // CJC 2005 if ray is primary ray ignore NO_IMAGE_FLAG to support the trace() SDL function
-    // TODO FIXME - I uess it would be better to have the trace() function use a different ray type [CLi]
+    // TODO FIXME - I guess it would be better to have the trace() function use a different ray type [CLi]
     return ( ( !ray.IsPhotonRay() &&
                (!Test_Flag(obj, NO_IMAGE_FLAG) || ray.IsImageRay() == false || ray.IsPrimaryRay() == true) &&
                (!Test_Flag(obj, NO_REFLECTION_FLAG) || ray.IsReflectionRay() == false) &&

source/core/shape/polynomial.cpp

@@ -10,7 +10,7 @@
 /// @parblock
 ///
 /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
-/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
 ///
 /// POV-Ray is free software: you can redistribute it and/or modify
 /// it under the terms of the GNU Affero General Public License as
@@ -145,7 +145,7 @@ bool Poly::Set_Coeff(const unsigned int x, const unsigned int y, const unsigned
         return false;
     }
     /* pos = binomials[a+2][3]+binomials[b+1][2]+binomials[c][1];
-     * rewriten to stay in bound (max is "Order", not Order+2)
+     * rewritten to stay in bound (max is "Order", not Order+2)
      */
     pos =
         // binomials[a+2][3]
@@ -157,14 +157,14 @@ bool Poly::Set_Coeff(const unsigned int x, const unsigned int y, const unsigned
         +binomials[b][1]+binomials[b][2]
         +binomials[c][1];
     /* It's magic
-     * Nah... a is the tetraedric sum to jump to get to the power of x index (first entry)
+     * Nah... a is the tetrahedral sum to jump to get to the power of x index (first entry)
      * b is then the triangular sum to add to get to the power of y index (also first entry)
      * and c is the linear sum to add to get to the power of z index (that the one we want)
-   *
+     *
      * Notice that binomials[c][1] == c, but the formula would loose its magic use of
      * pascal triangle everywhere.
-     * triangular sum are in the third ([2] column)
-     * tetraedric sum are in the fourth ([3] column)
+     * triangular sums are in the third ([2] column)
+     * tetrahedral sums are in the fourth ([3] column)
      *
      * (and yes, the 0 at the start of each column is useful)
      */

source/frontend/processoptions.h

@@ -9,7 +9,7 @@
 /// @parblock
 ///
 /// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
-/// Copyright 1991-2017 Persistence of Vision Raytracer Pty. Ltd.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
 ///
 /// POV-Ray is free software: you can redistribute it and/or modify
 /// it under the terms of the GNU Affero General Public License as
@@ -90,9 +90,16 @@ class ProcessOptions
         static bool IsTrue(const char *);
         static bool IsFalse(const char *);
 
+        /// @todo This should be in the POVMS module.
+        /// @note The attribute will be encoded as UCS2 with a trailing NUL byte.
         static int POVMSAttr_GetUTF8String(POVMSAttributePtr attr, POVMSType type, UTF8String& s);
+        /// @todo This should be in the POVMS module.
+        /// @note The attribute must be encoded as UCS2 with a trailing NUL byte.
         static int POVMSAttr_SetUTF8String(POVMSAttributePtr, POVMSType, const char *);
+        /// @todo This should be in the POVMS module.
+        /// @note The attribute will be encoded as UCS2 with a trailing NUL byte.
         static int POVMSUtil_SetUTF8String(POVMSObjectPtr, POVMSType, const char *);
+
         static size_t ConvertUTF16ToUTF8(const UTF16 *source, UTF8String& dest);
         static size_t ConvertUCS2ToUTF8(const UCS2 *source, UTF8String& dest);
     protected:

source/parser/parser.cpp

@@ -10390,7 +10390,7 @@ void Parser::Warn_Compat(bool definite, const char *syn)
     }
 
     Warning("%s\n"
-            "  Use of this syntax %s backwards compatable with earlier versions of POV-Ray.\n"
+            "  Use of this syntax %s backwards compatible with earlier versions of POV-Ray.\n"
             "  The #version directive or +MV switch will not help.",
             syn, text);
 }

source/parser/parser_expressions.cpp

@@ -3184,6 +3184,7 @@ shared_ptr<MAP_T> Parser::Parse_Blend_List (int Count, ColourBlendMapConstPtr De
             END_EXPECT
             break;
 
+            // TODO - what about kBlendMapType_Slope ?!
     }
 
     if ((Blend_Type==kBlendMapType_Normal) && (i==0))

source/parser/parser_strings.cpp

@@ -881,15 +881,15 @@ UCS2 *Parser::String_Literal_To_UCS2(const char *str, bool pathname)
             if ((char_array[index_in] == '\\') && pathname)
             {
                 // Historically, escape sequences were ignored when parsing for a filename.
-                // As of POV-Ray 3.8, this has been changed.
+                // As of POV-Ray v3.8, this has been changed.
 
 #if POV_BACKSLASH_IS_PATH_SEPARATOR
                 Warning("Backslash encountered while parsing for a filename."
-                        " In legacy (pre-3.8) scenes, this is NOT interpreted as the start of an escape sequence."
+                        " In legacy (pre-v3.8) scenes, this is NOT interpreted as the start of an escape sequence."
                         " However, for future compatibility it is recommended to use a forward slash as path separator instead.");
 #else
                 Warning("Backslash encountered while parsing for a filename."
-                        " In legacy (pre-3.8) scenes, this is NOT interpreted as the start of an escape sequence.");
+                        " In legacy (pre-v3.8) scenes, this is NOT interpreted as the start of an escape sequence.");
 #endif
             }
 

unix/configure.ac

@@ -1204,7 +1204,7 @@ AC_RUN_IFELSE([
       ],[
         AC_MSG_RESULT([yes])
         AC_DEFINE([HAVE_INF],           [],[infinite floating point values are supported])
-        AC_DEFINE([HAVE_EMULATED_ISINF],[],[infinities can be identified by them comparing non-equal to themselves])
+        AC_DEFINE([HAVE_EMULATED_ISINF],[],[infinities can be identified by comparison to the maximum value])
       ],[
         # although double and float support infinite values, they are no use to us as we can't properly test for them,
         # so we're not setting HAVE_INF.

unix/icons/source/Makefile

@@ -1,5 +1,5 @@
 ### Makefile --- 
-#   Makefile for POV-Ray 3.6 for UNIX icons
+#   Makefile for POV-Ray v3.6 for UNIX icons
 
 ## Author: [email protected]
 ## Version: $Id: Makefile,v 0.0 2004/05/12 16:21:28 chris Exp $

windows/winprecomp.cpp

@@ -1,9 +1,36 @@
-/*******************************************************************************
- * $File: //depot/public/povray/3.x/windows/winprecomp.cpp $
- * $Revision: #1 $
- * $Change: 6069 $
- * $DateTime: 2013/11/06 11:59:40 $
- * $Author: chrisc $
- *******************************************************************************/
+//******************************************************************************
+///
+/// @file windows/winprecomp.cpp
+///
+/// Used in header pre-compilation.
+///
+/// @copyright
+/// @parblock
+///
+/// Persistence of Vision Ray Tracer ('POV-Ray') version 3.8.
+/// Copyright 1991-2018 Persistence of Vision Raytracer Pty. Ltd.
+///
+/// POV-Ray is free software: you can redistribute it and/or modify
+/// it under the terms of the GNU Affero General Public License as
+/// published by the Free Software Foundation, either version 3 of the
+/// License, or (at your option) any later version.
+///
+/// POV-Ray is distributed in the hope that it will be useful,
+/// but WITHOUT ANY WARRANTY; without even the implied warranty of
+/// MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+/// GNU Affero General Public License for more details.
+///
+/// You should have received a copy of the GNU Affero General Public License
+/// along with this program.  If not, see <http://www.gnu.org/licenses/>.
+///
+/// ----------------------------------------------------------------------------
+///
+/// POV-Ray is based on the popular DKB raytracer version 2.12.
+/// DKBTrace was originally written by David K. Buck.
+/// DKBTrace Ver 2.0-2.12 were written by David K. Buck & Aaron A. Collins.
+///
+/// @endparblock
+///
+//******************************************************************************
 
 #include "winprecomp.h"