Merge pull request #1066 from Idclip/doc_fixes

Doxygen fixes and improvements

.github/workflows/docs.yml

@@ -20,7 +20,7 @@ on:
 
 jobs:
   doxygen:
-    runs-on: ubuntu-16.04
+    runs-on: ubuntu-latest
     env:
       CXX: g++
     container:
@@ -32,7 +32,7 @@ jobs:
     - name: install_epydoc
       run: pip install epydoc
     - name: install_latex
-      run: yum -y install texlive-latex-bin texlive-dvips
+      run: yum -y install texlive-latex-bin texlive-dvips texlive-collection-fontsrecommended texlive-collection-latexrecommended
     - name: build
       run: ./ci/build.sh Release None OFF None "core,python,doc" -DOPENVDB_PYTHON_WRAP_ALL_GRID_TYPES=ON -DDISABLE_DEPENDENCY_VERSION_CHECKS=ON
     - name: epydoc

doc/CMakeLists.txt

@@ -55,7 +55,8 @@ set(DOXY_FILES
 set(DOXYGEN_PROJECT_NAME "OpenVDB")
 set(DOXYGEN_PROJECT_NUMBER "${OpenVDB_VERSION}")
 set(DOXYGEN_PROJECT_BRIEF "")
-set(DOXYGEN_FILE_PATTERNS "*.h") # headers only
+set(DOXYGEN_FILE_PATTERNS *.h *h.in) # headers only
+set(DOXYGEN_EXTENSION_MAPPING .in=C) # parse CMake config headers as C
 set(DOXYGEN_IMAGE_PATH "doc/img")
 set(DOXYGEN_RECURSIVE NO)
 

doc/changes.txt

@@ -32,7 +32,7 @@ Improvements:
   Performance gains will improve relative to increases in the inputs size
   and dilation scheme.
 - Added an optional argument to
-  @vdblink::Tree::topologyUnion() Tree::topologyUnion@endlink which preserves
+  @vdblink::tree::Tree::topologyUnion() Tree::topologyUnion@endlink which preserves
   active tiles on the destination tree should they overlap leaf nodes from the
   source tree.
 - Reduced the time spent in the hot path of @vdblink::initialize() initialize@endlink

openvdb/openvdb/version.h.in

@@ -51,20 +51,26 @@
 ///////////////////////////////////////////////////////////////////////////////
 ///////////////////////////////////////////////////////////////////////////////
 
-/// @brief  Auto generated build configurations from CMake
+// Auto generated build configurations from CMake
 
-/* Library major, minor and patch version numbers */
+///@{
+/// @brief Library major, minor and patch version numbers
+/// @hideinitializer
 #define OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER ${OpenVDB_MAJOR_VERSION}
+/// @hideinitializer
 #define OPENVDB_LIBRARY_MINOR_VERSION_NUMBER ${OpenVDB_MINOR_VERSION}
+/// @hideinitializer
 #define OPENVDB_LIBRARY_PATCH_VERSION_NUMBER ${OpenVDB_PATCH_VERSION}
+///@}
 
-/* The ABI version that OpenVDB was built with */
 /// @note  This ifndef exists for compatibility with older versions of OpenVDB.
 ///   This value should never be different from the value configured when
 ///   OpenVDB was built, but this previously needed to be defined by downstream
 ///   software. Redefining it here would cause build failures, so this allows
 ///   users to transition and remove the define in their build systems.
 #ifndef OPENVDB_ABI_VERSION_NUMBER
+/// @brief The ABI version that OpenVDB was built with
+/// @hideinitializer
 #define OPENVDB_ABI_VERSION_NUMBER ${OPENVDB_ABI_VERSION_NUMBER}
 #endif
 
@@ -82,31 +88,31 @@
 /// @hideinitializer
 #define OPENVDB_LIBRARY_ABI_VERSION_STRING "${OpenVDB_MAJOR_VERSION}.${OpenVDB_MINOR_VERSION}.${OpenVDB_PATCH_VERSION}abi${OPENVDB_ABI_VERSION_NUMBER}"
 
-/// Library version number as a packed integer ("%02x%02x%04x", major, minor, patch)
+/// @brief Library version number as a packed integer ("%02x%02x%04x", major, minor, patch)
+/// @hideinitializer
 #define OPENVDB_LIBRARY_VERSION_NUMBER ${OPENVDB_PACKED_VERSION}
 
+/// @brief The version namespace name for this library version
+/// @hideinitializer
+///
+/// When the ABI version number matches the library major version number,
+/// symbols are named as in the following examples:
+/// - @b openvdb::vX_Y::Vec3i
+/// - @b openvdb::vX_Y::io::File
+/// - @b openvdb::vX_Y::tree::Tree
+///
+/// where X and Y are the major and minor version numbers.
+///
+/// When the ABI version number does not match the library major version number,
+/// symbol names include the ABI version:
+/// - @b openvdb::vX_YabiN::Vec3i
+/// - @b openvdb::vX_YabiN::io::File
+/// - @b openvdb::vX_YabiN::tree::Tree
+///
+/// where X, Y and N are the major, minor and ABI version numbers, respectively.
 #if OPENVDB_ABI_VERSION_NUMBER == OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER
-    /// @brief The version namespace name for this library version
-    /// @hideinitializer
-    ///
-    /// When the ABI version number matches the library major version number,
-    /// symbols are named as in the following examples:
-    /// - @b openvdb::vX_Y::Vec3i
-    /// - @b openvdb::vX_Y::io::File
-    /// - @b openvdb::vX_Y::tree::Tree
-    ///
-    /// where X and Y are the major and minor version numbers.
-    ///
-    /// When the ABI version number does not match the library major version number,
-    /// symbol names include the ABI version:
-    /// - @b openvdb::vX_YabiN::Vec3i
-    /// - @b openvdb::vX_YabiN::io::File
-    /// - @b openvdb::vX_YabiN::tree::Tree
-    ///
-    /// where X, Y and N are the major, minor and ABI version numbers, respectively.
     #define OPENVDB_VERSION_NAME v${OpenVDB_MAJOR_VERSION}_${OpenVDB_MINOR_VERSION}
 #else
-    // This duplication of code is necessary to avoid issues with recursive macro expansion.
     #define OPENVDB_VERSION_NAME v${OpenVDB_MAJOR_VERSION}_${OpenVDB_MINOR_VERSION}abi${OPENVDB_ABI_VERSION_NUMBER}
 #endif
 
@@ -177,14 +183,17 @@ namespace OPENVDB_VERSION_NAME {
 /// @details This can be used to quickly test whether we have a valid file or not.
 const int32_t OPENVDB_MAGIC = 0x56444220;
 
-// Library major, minor and patch version numbers
+/// Library major, minor and patch version numbers
+/// @hideinitializer
 const uint32_t
     OPENVDB_LIBRARY_MAJOR_VERSION = OPENVDB_LIBRARY_MAJOR_VERSION_NUMBER,
     OPENVDB_LIBRARY_MINOR_VERSION = OPENVDB_LIBRARY_MINOR_VERSION_NUMBER,
     OPENVDB_LIBRARY_PATCH_VERSION = OPENVDB_LIBRARY_PATCH_VERSION_NUMBER;
 /// Library version number as a packed integer ("%02x%02x%04x", major, minor, patch)
+/// @hideinitializer
 const uint32_t OPENVDB_LIBRARY_VERSION = OPENVDB_LIBRARY_VERSION_NUMBER;
-// ABI version number
+/// ABI version number
+/// @hideinitializer
 const uint32_t OPENVDB_ABI_VERSION = OPENVDB_ABI_VERSION_NUMBER;
 
 /// @brief The current version number of the VDB file format

openvdb_ax/openvdb_ax/codegen/FunctionTypes.h

@@ -823,7 +823,7 @@ struct FunctionGroup
     ///         signature, generate and execute the function body. Returns the
     ///         return value of the function (nullptr if void). The behaviour
     ///         is undefined if a valid match does not exist. For such cases,
-    ///         call the second version of ::execute.
+    ///         call the second version of FunctionGroup::execute.
     /// @note   This function will throw if no valid return is provided by the
     ///         matched declaration implementation.
     ///

openvdb_ax/openvdb_ax/compiler/PointExecutable.h

@@ -43,7 +43,8 @@ class Compiler;
 ///   executable object; immutable except for execution settings and implements
 ///   'execute' functions which can be called multiple times for arbitrary sets
 ///   of inputs. The intended usage of these executables is to configure their
-///   runtime arguments and then call ::execute with your VDBs. For example:
+///   runtime arguments and then call PointExecutable::execute with your VDBs.
+///   For example:
 /// @code
 ///   PointExecutable::Ptr exe = compiler.compile<PointExecutable>("@a += 1");
 ///   exe->setCreateMissing(false); // fail on missing attributes
@@ -62,6 +63,8 @@ class Compiler;
 ///   - Grain size: 1
 ///       The default grain sizes passed to the tbb partitioner for leaf level
 ///       processing.
+///       @sa setGrainSize
+///
 ///  For more in depth information, see the @ref vdbaxcompilerexe documentation.
 class PointExecutable
 {

openvdb_ax/openvdb_ax/compiler/VolumeExecutable.h

@@ -42,7 +42,8 @@ class Compiler;
 ///   executable object; immutable except for execution settings and implements
 ///   'execute' functions which can be called multiple times for arbitrary sets
 ///   of inputs. The intended usage of these executables is to configure their
-///   runtime arguments and then call ::execute with your VDBs. For example:
+///   runtime arguments and then call VolumeExecutable::execute with your VDBs.
+///   For example:
 /// @code
 ///   VolumeExecutable::Ptr exe = compiler.compile<VolumeExecutable>("@a += 1");
 ///   exe->setTreeExecutionLevel(0); // only process leaf nodes
@@ -58,15 +59,18 @@ class Compiler;
 ///   - Iteration Type: ON
 ///       By default, processes ACTIVE values.
 ///       @sa setValueIterator
-///   - Active Tile Streaming: ON or OFF depending on AX code.
+///   - Active Tile Streaming: ON, OFF or AUTO depending on AX code.
 ///       By default, if AX detects that the AX program may produce unique
 ///       values for leaf level voxels that would otherwise comprise a
-///       given active tile, this setting is set to ON. Otherwise it is set to
-///       OFF.
+///       given active tile, this setting is set to ON or AUTO. Otherwise it is
+///       set to OFF.
 ///       @sa setActiveTileStreaming
 ///   - Grain sizes: 1:32
 ///       The default grain sizes passed to the tbb partitioner for leaf level
 ///       processing and active tile processing.
+///       @sa setGrainSize
+///       @sa setActiveTileStreamingGrainSize
+///
 ///  For more in depth information, see the @ref vdbaxcompilerexe documentation.
 class VolumeExecutable
 {
@@ -93,7 +97,7 @@ class VolumeExecutable
     ///
     /// @param grids  The VDB Volumes to process
     void execute(openvdb::GridPtrVec& grids) const;
-    void execute(openvdb::GridBase& grid) const;
+    void execute(openvdb::GridBase& grids) const;
     ///@}
 
     ////////////////////////////////////////////////////////
@@ -117,30 +121,34 @@ class VolumeExecutable
     ///   than the root node's level) will cause this method to throw a runtime
     ///   error.
     /// @param min The minimum tree execution level to set
-    /// @param min The maximum tree execution level to set
+    /// @param max The maximum tree execution level to set
     void setTreeExecutionLevel(const Index min, const Index max);
     /// @param level The tree execution level to set. Calls setTreeExecutionLevel
     ///   with min and max arguments as level.
     void setTreeExecutionLevel(const Index level);
-    /// @return  Get the tree execution levels.
+    /// @brief  Get the tree execution levels.
+    /// @param min The minimum tree execution level
+    /// @param max The maximum tree execution level
     void getTreeExecutionLevel(Index& min, Index& max) const;
 
     /// @brief  The streaming type of active tiles during execution.
-    ///   ON: active tiles are temporarily densified (converted to leaf level
-    ///     voxels) on an "as needed" basis and the subsequent voxel values are
-    ///     processed. The temporarily densified node is added to the tree only
-    ///     if a non constant voxel buffer is produced. Otherwise a child tile
-    ///     may be created or the original tile's value may simply be modified.
-    ///  OFF: tile topologies are left unchanged and their single value is
+    /// @param  ON active tiles are temporarily densified (converted to leaf
+    ///     level voxels) on an "as needed" basis and the subsequent voxel
+    ///     values are processed. The temporarily densified node is added to the
+    ///     tree only if a non constant voxel buffer is produced. Otherwise a
+    ///     child tile may be created or the original tile's value may simply be
+    ///     modified.
+    /// @param  OFF tile topologies are left unchanged and their single value is
     ///     processed.
-    ///  AUTO: the volume executable analyzes the compiled kernel and attempts
-    ///     to determine if expansion of active tiles would lead to different,
-    ///     non-constant values in the respective voxels. This is done on a per
-    ///     grid basis; ultimately each execution will be set to ON or OFF.
-    ///     This option will always fall back to ON if there is any chance the
-    ///     kernel may produce child nodes
-    ///   The volume executable always runs an AUTO check on creation and will
-    ///   set itself to ON (if all grids always need child nodes), OFF (if
+    /// @param  AUTO the volume executable analyzes the compiled kernel and
+    ///     attempts to determine if expansion of active tiles would lead to
+    ///     different, non-constant values in the respective voxels. This is
+    ///     done on a per grid basis; ultimately each execution will be set to
+    ///     ON or OFF. This option will always fall back to ON if there is any
+    ///     chance the kernel may produce child nodes
+    ///
+    /// @note The volume executable always runs an AUTO check on creation and
+    ///   will set itself to ON (if all grids always need child nodes), OFF (if
     ///   grids never need child nodes) or remains as AUTO (if this depends on
     ///   which grid is being processed).
     ///
@@ -149,33 +157,36 @@ class VolumeExecutable
     ///   unique voxels such that they can each receive a unique value. For
     ///   example, consider the following AX code which assigns a vector volume
     ///   to the world space position of each voxel:
+    /// @code
     ///      v@v = getvoxelpws();
-    ///
+    /// @endcode
     ///   Active tiles hold a single value but comprise an area greater than
     ///   that of a single voxel. As the above kernel varies with respect to
     ///   a nodes position, we'd need to replace these tiles with leaf voxels
     ///   to get unique per node values. The stream flag is initialised to ON
     ///   in this case.
     ///
     ///   This behaviour, however, is not always desirable .i.e:
+    /// @code
     ///      v@v = {1,2,3};
-    ///
+    /// @endcode
     ///   In this instance, all values within a volume receive the same value
     ///   and are not dependent on any spatially or iteratively varying
     ///   metrics. The stream flag is set to OFF.
     ///
     ///   The AUTO flag is set in cases where the runtime access pattern of the
     ///   inputs determines streaming:
+    /// @code
     ///     f@density = f@mask;
     ///     f@mask = 0;
-    ///
-    ///   In this instance, the runtime topology and values of @mask determines
-    ///   whether child topology needs to be created in @density, but @mask
+    /// @endcode
+    ///   In this instance, the runtime topology and values of \@mask determines
+    ///   whether child topology needs to be created in \@density, but \@mask
     ///   itself does not need streaming. Streaming will be set to ON for
     ///   density but OFF for mask.
     ///
     /// @note This behaviour is only applied to active tiles. If the value
-    ///   iterator is set to OFF (@sa setValueIterator), this option is ignored.
+    ///   iterator is set to OFF, this option is ignored.
     /// @warning  This option can generate large amounts of leaf level voxels.
     ///   It is recommended to use a good concurrent memory allocator (such as
     ///   jemalloc) for the best performance.
@@ -217,15 +228,15 @@ class VolumeExecutable
     /// @note Setting g1 or g2 to zero has the effect of disabling
     ///  multi-threading for the respective node executions. Setting both to
     ///  zero will disable all multi-threading performed by the execute method.
-    /// @param g1  The grain size used for non streamed nodes (leafs or tiles)
-    /// @param g2  The grain size used for streamed execution (active tiles)
     void setGrainSize(const size_t g1);
     void setActiveTileStreamingGrainSize(const size_t g2);
     /// @return  The current g1 grain size
+    /// @sa setGrainSize
     size_t getGrainSize() const;
     /// @return  The current g2 grain size
+    /// @sa setActiveTileStreamingGrainSize
     size_t getActiveTileStreamingGrainSize() const;
-    ///}@
+    ///@}