[ci skip] Some source documentation work.

distribution/dirinfo.dox

@@ -0,0 +1,23 @@
+/**
+
+@dir
+@brief Files and directories to be distributed as-is to the end-user.
+
+This directory is designated to bundle all files which are to be distributed
+as-is to POV-Ray end users.
+
+@note
+    Generally, the contents of this directory are to be distributed to end-users
+    of _all_ _incarnations_ of POV-Ray. Files to be included only with one
+    particular incarnation (e.g. POV-Ray for Windows) should reside in aptly
+    named subdirectories of the @ref distribution/platform-specific directory.
+
+@attention
+    The build processes for the individual incarnations of POV-Ray are set up to
+    automatically include all files in the currently existing subdirectories,
+    as well as any relevant files in this directory itself. However, new
+    subdirectories, or new files in this directory, are _not_ automatically
+    included, and therefore require updates to the build processes of _all_
+    incarnations.
+
+*/

distribution/platform-specific/dirinfo.dox

@@ -0,0 +1,6 @@
+/**
+
+@dir
+@brief Files to be distributed as-is to the end-users of particular POV-Ray _incarnations_.
+
+*/

libraries/boost/readme-pov.dox

@@ -0,0 +1,14 @@
+/**
+
+@dir
+@ingroup PovLibraries
+@brief Source code of _boost_ 3rd party libraries (subset).
+
+This directory contains a subset of the boost 1.62.0 source code, and is
+part of the POV-Ray source distribution package.
+
+Official boost source code packages can be obtained via <https://www.boost.org>.
+
+See `LICENSE_1_0.txt` file in this directory for licensing information.
+
+*/

libraries/ilmbase/readme-pov.dox

@@ -0,0 +1,22 @@
+/**
+
+@dir
+@ingroup PovLibraries
+@brief Source code of _IlmBase_ 3rd party library (subset).
+
+This directory contains a subset of the IlmBase 2.2.0 source code release
+(being part of OpenEXR), and is part of the POV-Ray source distribution
+package.
+
+@note
+    The file `config.windows/IlmBaseConfig.h` differs from the original file in
+    that it has been patched to include version information in the same manner as
+    the non-Windows version of the file does. Furthermore, this distribution
+    omits various subdirectories containing files not required for the OpenEXR
+    library.
+
+Official IlmBase and OpenEXR source code releases can be obtained via <http://www.openexr.com>.
+
+See `LICENSE` file in this directory for licensing information.
+
+*/

libraries/jpeg/readme-pov.dox

@@ -0,0 +1,18 @@
+/**
+
+@dir
+@ingroup PovLibraries
+@brief Source code of _libjpeg_ 3rd party JPEG library.
+
+This directory contains a slightly adapted libjpeg 9 source distribution,
+and is part of the POV-Ray source distribution package.
+
+@note
+    This distribution of libjpeg differs from the original in the addition of
+    two config files, `jconfig.h` and `jconfig.pov`.
+
+Official libjpeg source distribution packages can be obtained via <http://ijg.org/>.
+
+See `README` file in this directory for licensing information.
+
+*/

libraries/openexr/readme-pov.dox

@@ -0,0 +1,21 @@
+/**
+
+@dir
+@ingroup PovLibraries
+@brief Source code of _OpenEXR_ 3rd party library (subset).
+
+This directory contains a subset of the OpenEXR 2.2.0 source code release,
+and is part of the POV-Ray source distribution package.
+
+@note
+    The file `config.windows/OpenEXRConfig.h` differs from the original file in
+    that it has been patched to include version information in the same manner as
+    the non-Windows version of the file does. Furthermore, this distribution
+    omits various subdirectories containing files not required to build the
+    library proper.
+
+Official IlmBase and OpenEXR source code releases can be obtained via <http://www.openexr.com>.
+
+See `LICENSE` file in this directory for licensing information.
+
+*/

libraries/png/readme-pov.dox

@@ -0,0 +1,20 @@
+/**
+
+@dir
+@ingroup PovLibraries
+@brief Source code of _libpng_ 3rd party PNG library (subset).
+
+This directory contains a subset of the libpng 1.5.14 source distribution,
+and is part of the POV-Ray source distribution package.
+
+@note
+    The `contrib` subdirectory of the official libpng source distribution
+    package is not included in the POV-Ray source distribution package, as its
+    contents are not part of libpng proper and are not required for building
+    the library.
+
+Official libpng source distribution packages can be obtained via <http://libpng.org/pub/png/libpng.html>.
+
+See `LICENSE` file in this directory for licensing information.
+
+*/

libraries/readme.txt → libraries/readme-pov.dox

@@ -1,12 +1,21 @@
-This directory contains the source code (or subsets thereof) of all the
+/**
+
+@defgroup PovLibraries 3rd Party Libraries
+@brief Source code for 3rd party libraries used by POV-Ray.
+
+@{
+
+@dir
+@brief Source code of @ref PovLibraries.
+
+This directory contains the source code (or relevant subsets thereof) of all the
 3rd party libraries required or recommended to build POV-Ray from scratch.
 
--------------------------------------------------------------------------------
-NOTE: The presence of this directory should _by no means_ be understood as a
-recommendation to use these particular versions of the libraries. To the
-contrary, on most platforms it is highly recommended to use up-to-date versions
-of the libraries instead.
--------------------------------------------------------------------------------
+@attention
+    The presence of this directory should _by no means_ be understood as a
+    recommendation to use these particular versions of the libraries. To the
+    contrary, on most platforms it is highly recommended to use up-to-date versions
+    of the libraries instead.
 
 Originally dating back to pre-Internet times when obtaining 3rd party libraries
 was non-trivial for everyone, the only reason for this directory's continued
@@ -20,3 +29,7 @@ problem was to set up our own custom build processes for these libraries, using
 the same tools as POV-Ray's own build process. However, this approach requires
 the use of well-defined versions of those libraries, which is exactly what this
 directory continues to provide.
+
+@}
+
+*/

libraries/tiff/readme-pov.dox

@@ -0,0 +1,19 @@
+/**
+
+@dir
+@ingroup PovLibraries
+@brief Source code of _libtiff_ 3rd party TIFF library.
+
+This directory contains a slightly adapted libtiff 3.8.2 source distribution,
+and is part of the POV-Ray source distribution package.
+
+@note
+    This distribution of libtiff differs from the original in the omission of
+    a config file, `libtiff/tiffconf.h`, which is instead re-created during the
+    build process.
+
+Official libtiff source distribution packages can be obtained via <http://simplesystems.org/libtiff/>.
+
+See `COPYRIGHT` file in this directory for licensing information.
+
+*/

libraries/zlib/readme-pov.dox

@@ -0,0 +1,16 @@
+/**
+
+@dir
+@ingroup PovLibraries
+@brief Source code of _zlib_ 3rd party compression library.
+
+This directory contains a copy of the zlib 1.2.7 source distribution,
+and is part of the POV-Ray source distribution package.
+
+The latest official zlib source distribution package can be obtained via
+<https://zlib.net>. Older versions may be found at the _libpng_ download site,
+accessible via <http://www.libpng.org/pub/png/libpng.html>.
+
+See `README` file in this directory for licensing information.
+
+*/

platform/dirinfo.dox

@@ -1,7 +1,13 @@
 /**
 
+@defgroup PovPlatform POV-Ray Platform-Specific Portions
+@brief Code specific to particular hardware platforms or operating systems.
+
+@{
+
 @dir
-@ingroup PovPlatform
-Source code files specific to individual operating systems or hardware platforms.
+@brief Source code files for @ref PovPlatform.
+
+@}
 
 */

platform/unix/dirinfo.dox

@@ -1,2 +1,7 @@
-/// @dir
-/// Source code files for optimizations and adaptations specific to the Unix family of operating systems.
+/**
+
+@dir
+@ingroup PovPlatform
+@brief Source code files for optimizations and adaptations specific to the Unix family of operating systems.
+
+*/

platform/windows/dirinfo.dox

@@ -1,2 +1,7 @@
-/// @dir
-/// Source code files for optimizations and adaptations specific to the Windows operating system.
+/**
+
+@dir
+@ingroup PovPlatform
+@brief Source code files for optimizations and adaptations specific to the Windows operating system.
+
+*/

platform/x86/avx/dirinfo.dox

@@ -1,6 +1,11 @@
-/// @dir
-/// Source code files containing AVX-specific implementations of dynamically dispatched code.
-///
-/// The files in this directory contain code that is intended for dynamic dispatch,
-/// and therefore may need to be compiled with different options than the rest of POV-Ray.
-/// For instance, to compile these files with gcc, the `-mavx` flag will be needed.
+/**
+
+@dir
+@ingroup PovPlatform
+@brief Source code files containing AVX-specific implementations of dynamically dispatched code.
+
+The files in this directory contain code that is intended for dynamic dispatch,
+and therefore may need to be compiled with different options than the rest of POV-Ray.
+For instance, to compile these files with gcc, the `-mavx` flag will be needed.
+
+*/

platform/x86/avx2fma3/dirinfo.dox

@@ -1,6 +1,11 @@
-/// @dir
-/// Source code files containing AVX2/FMA3-specific implementations of dynamically dispatched code.
-///
-/// The files in this directory contain code that is intended for dynamic dispatch,
-/// and therefore may need to be compiled with different options than the rest of POV-Ray.
-/// For instance, to compile these files with gcc, the `-mavx2 -fma3` flags will be needed.
+/**
+
+@dir
+@ingroup PovPlatform
+@brief Source code files containing AVX2/FMA3-specific implementations of dynamically dispatched code.
+
+The files in this directory contain code that is intended for dynamic dispatch,
+and therefore may need to be compiled with different options than the rest of POV-Ray.
+For instance, to compile these files with gcc, the `-mavx2 -fma3` flags will be needed.
+
+*/

platform/x86/avxfma4/dirinfo.dox

@@ -1,6 +1,11 @@
-/// @dir
-/// Source code files containing AVX/FMA4-specific implementations of dynamically dispatched code.
-///
-/// The files in this directory contain code that is intended for dynamic dispatch,
-/// and therefore may need to be compiled with different options than the rest of POV-Ray.
-/// For instance, to compile these files with gcc, the `-mavx -fma4` flags will be needed.
+/**
+
+@dir
+@ingroup PovPlatform
+@brief Source code files containing AVX/FMA4-specific implementations of dynamically dispatched code.
+
+The files in this directory contain code that is intended for dynamic dispatch,
+and therefore may need to be compiled with different options than the rest of POV-Ray.
+For instance, to compile these files with gcc, the `-mavx -fma4` flags will be needed.
+
+*/

platform/x86/dirinfo.dox

@@ -1,2 +1,7 @@
-/// @dir
-/// Source code files for optimizations specific to x86-based hardware platforms.
+/**
+
+@dir
+@ingroup PovPlatform
+@brief Source code files for optimizations specific to x86-based hardware platforms.
+
+*/

source-doc/dirinfo.dox

@@ -0,0 +1,17 @@
+/**
+
+@dir
+@brief Auxiliary information for developers and contributors.
+
+This directory contains miscellaneous information aimed at POV-Ray
+developers and potential contributors. The information is provided in
+Doxygen-flavoured markdown files to allow for reasonably easy reading and
+editing of the raw files, while at the same time allowing for easy inclusion
+of the information in auto-generated source code documentation.
+
+In addition, this directory also serves as a home for some odss & ends of
+the source code documentation proper, which don't seem to properly fit
+in any particular source code file. Such bits and pieces reside in
+Doxygen-style `.dox` files.
+
+*/

source-doc/incarnations.md

@@ -0,0 +1,22 @@
+@page incarnations  POV-Ray Incarnations
+
+POV-Ray comes in different _incarnations_, that is, particular applications that
+differ in the user interface and/or the operating system they are designed for;
+for example, _POV-Ray for Windows_ is one such incarnation of POV-Ray.
+
+
+Creating a New POV-Ray Incarnation
+==================================
+
+If you want to develop a new incarnation of POV-Ray, here are a few things you
+should look out for:
+
+  - Make sure your build process automatically picks up on any newly added or
+    removed source code files in the @ref source directory (including new
+    sub-directories). Developers working on the incarnation-neutral modules of
+    POV-Ray _will_ add or remove such files comparatively frequently without
+    warning.
+
+  - In the same vein, make sure your distribution process automatically picks up
+    on any newly added or removed files in existing sub-directories of the
+    @ref distribution directory.