Wrapped all internal API sections in doxygen conditions OPENVDB_DOCS_INTERNAL

Signed-off-by: Nick Avramoussis <[email protected]>

Author: Idclip

CHANGES

@@ -1544,8 +1544,7 @@ Version 3.2.0 - August 10, 2016
     - Fixed isApproxZero() so that it works correctly when tolerance is zero.
       [Reported by Joshua Olson]
     - Fixed bugs in tree::NodeUnion that could cause crashes.
-    - Fixed memory leak in
-      tools::mesh_to_volume_internal::ExpandNarrowband
+    - Fixed memory leak in a tools::meshToVolume sub-tool (expandNarrowband).
       [Reported by Kévin Dietrich]
     - Fixed parameter type inconsistencies in math/Stencils.h and
       tools/RayIntersector.h.

doc/CMakeLists.txt

@@ -19,8 +19,11 @@ include(GNUInstallDirs)
 # with OPENVDB_BUILD_DOCS=ON and either OPENVDB_BUILD_HOUDINI_PLUGIN=ON or
 # USE_HOUDINI=ON will define Houdini_VERSION. If Houdini_VERSION is not set,
 # all documentation is included.
-option(OPENVDB_DOXYGEN_HOUDINI "Build Houdini documentation" ON)
 option(OPENVDB_DOXYGEN_AX "Build AX documentation" ON)
+option(OPENVDB_DOXYGEN_HOUDINI "Build Houdini documentation" ON)
+option(OPENVDB_DOXYGEN_INTERNAL [=[
+Enable documentation of methods and classes which have been explicitly marked as internal
+]=] OFF)
 
 find_package(Doxygen REQUIRED doxygen)
 if(MINIMUM_DOXYGEN_VERSION)
@@ -59,10 +62,12 @@ 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)
+set(DOXYGEN_QUIET YES)
 
 set(DOXYGEN_GENERATE_HTML YES)
 set(DOXYGEN_GENERATE_MAN NO)
 set(DOXYGEN_GENERATE_LATEX NO)
+set(DOXYGEN_GENERATE_TODOLIST NO)
 
 set(DOXYGEN_HTML_COLORSTYLE_HUE 4)
 set(DOXYGEN_HTML_COLORSTYLE_SAT 222)
@@ -72,18 +77,32 @@ set(DOXYGEN_EXTRACT_ALL YES)
 set(DOXYGEN_EXTRACT_STATIC YES)
 set(DOXYGEN_EXTRACT_LOCAL_CLASSES NO)
 
+# Allow for root directory paths to be listed (e.g. openvdb/io/File.h)
+# Rather than just the file names (e.g. File.h). This makes it far
+# easier to navigate the docs
+set(DOXYGEN_FULL_PATH_NAMES YES)
+# Should be the same as the WORKING_DIRECTORY argument to doxygen_add_docs
+set(DOXYGEN_STRIP_FROM_PATH "${CMAKE_SOURCE_DIR}")
+set(DOXYGEN_STRIP_FROM_INC_PATH
+  "${CMAKE_SOURCE_DIR}/openvdb"
+  "${CMAKE_SOURCE_DIR}/openvdb_ax"
+  "${CMAKE_SOURCE_DIR}/openvdb_houdini")
+# Shows which source files generated the respected doxygen docs
+# at the bottom of each html page. Don't bother listing these.
+set(DOXYGEN_SHOW_USED_FILES NO)
+# When doxygen adds the source code for each header (see VERBATIM_HEADERS)
+# don't remove the actual doxygen comments
+set(DOXYGEN_STRIP_CODE_COMMENTS NO)
+# Don't add an alpha index of all classes (it's not particularly useful)
 set(DOXYGEN_ALPHABETICAL_INDEX NO)
 set(DOXYGEN_DISTRIBUTE_GROUP_DOC YES)
-set(DOXYGEN_FULL_PATH_NAMES NO)
-set(DOXYGEN_GENERATE_TODOLIST NO)
 set(DOXYGEN_HIDE_IN_BODY_DOCS YES)
 set(DOXYGEN_HIDE_SCOPE_NAMES YES)
 set(DOXYGEN_INLINE_INHERITED_MEMB YES)
 set(DOXYGEN_MACRO_EXPANSION YES)
-set(DOXYGEN_CLASS_DIAGRAMS NO) # @todo use dot with class diagrams for relevant classes
-set(DOXYGEN_ENABLED_SECTIONS "")
+# @todo use dot with class diagrams for relevant classes
+set(DOXYGEN_CLASS_DIAGRAMS NO)
 
-set(DOXYGEN_QUIET YES)
 
 set(DOXYGEN_ALIASES
   [[ijk="(<i>i</i>,&nbsp;<i>j</i>,&nbsp;<i>k</i>)"]]
@@ -117,6 +136,12 @@ set(DOXYGEN_PREDEFINED
   [[__declspec(x):= __attribute__(x):=]]
   "OPENVDB_USE_LOG4CPLUS=")
 
+set(DOXYGEN_ENABLED_SECTIONS "")
+
+if(OPENVDB_DOXYGEN_INTERNAL)
+  list(APPEND DOXYGEN_ENABLED_SECTIONS "OPENVDB_DOCS_INTERNAL")
+endif()
+
 if(OPENVDB_DOXYGEN_HOUDINI)
   # Append Houdini-specific settings to the Doxygen config file.
   if(Houdini_VERSION)

doc/changes.txt

@@ -1954,9 +1954,8 @@ Bug fixes:
   <I>[Reported by Joshua&nbsp;Olson]</I>
 - Fixed bugs in @vdblink::tree::NodeUnion NodeUnion@endlink that could cause
   crashes.
-- Fixed memory leak in
-  @vdblink::tools::mesh_to_volume_internal::ExpandNarrowband
-  tools::mesh_to_volume_internal::ExpandNarrowband@endlink
+- Fixed memory leak in a @vdblink::tools::meshToVolume tools::meshToVolume@endlink
+  sub-tool (expandNarrowband).
   <I>[Reported by K&eacute;vin&nbsp;Dietrich]</I>
 - Fixed parameter type inconsistencies in @link math/Stencils.h@endlink and
   @link tools/RayIntersector.h@endlink.

openvdb/openvdb/Grid.h

@@ -1779,6 +1779,7 @@ createLevelSet(Real voxelSize, Real halfWidth)
 
 ////////////////////////////////////////
 
+/// @cond OPENVDB_DOCS_INTERNAL
 
 namespace internal {
 
@@ -1803,6 +1804,7 @@ struct GridApplyImpl<OpT, GridBaseT, TypeList<GridT, GridTs...>>
 
 } // namespace internal
 
+/// @endcond
 
 template<typename GridTypeListT, typename OpT>
 inline bool

openvdb/openvdb/Platform.h

@@ -10,15 +10,15 @@
 
 /// @name Utilities
 /// @{
-/// @cond OPENVDB_VERSION_INTERNAL
+/// @cond OPENVDB_DOCS_INTERNAL
 #define OPENVDB_PREPROC_STRINGIFY_(x) #x
 /// @endcond
 /// @brief Return @a x as a string literal.  If @a x is a macro,
 /// return its value as a string literal.
 /// @hideinitializer
 #define OPENVDB_PREPROC_STRINGIFY(x) OPENVDB_PREPROC_STRINGIFY_(x)
 
-/// @cond OPENVDB_VERSION_INTERNAL
+/// @cond OPENVDB_DOCS_INTERNAL
 #define OPENVDB_PREPROC_CONCAT_(x, y) x ## y
 /// @endcond
 /// @brief Form a new token by concatenating two existing tokens.

openvdb/openvdb/TypeList.h

@@ -21,7 +21,7 @@ namespace openvdb {
 OPENVDB_USE_VERSION_NAMESPACE
 namespace OPENVDB_VERSION_NAME {
 
-/// @cond OPENVDB_TYPES_INTERNAL
+/// @cond OPENVDB_DOCS_INTERNAL
 
 template<typename... Ts> struct TypeList; // forward declaration
 

openvdb/openvdb/Types.h

@@ -317,7 +317,7 @@ template<typename FromType, typename ToType> struct CopyConstness {
     using Type = typename std::remove_const<ToType>::type;
 };
 
-/// @cond OPENVDB_TYPES_INTERNAL
+/// @cond OPENVDB_DOCS_INTERNAL
 template<typename FromType, typename ToType> struct CopyConstness<const FromType, ToType> {
     using Type = const ToType;
 };

openvdb/openvdb/math/LegacyFrustum.h

@@ -17,6 +17,9 @@ namespace openvdb {
 OPENVDB_USE_VERSION_NAMESPACE
 namespace OPENVDB_VERSION_NAME {
 namespace math {
+
+/// @cond OPENVDB_DOCS_INTERNAL
+
 namespace internal {
 
 /// @brief LegacyFrustum class used at DreamWorks for converting old vdb files.
@@ -158,6 +161,9 @@ class LegacyFrustum
 };
 
 } // namespace internal
+
+/// @endcond
+
 } // namespace math
 } // namespace OPENVDB_VERSION_NAME
 } // namespace openvdb

openvdb/openvdb/math/Operators.h

@@ -75,6 +75,7 @@ struct OpMagnitude {
     }
 };
 
+/// @cond OPENVDB_DOCS_INTERNAL
 
 namespace internal {
 
@@ -87,6 +88,8 @@ struct ReturnValue {
 
 } // namespace internal
 
+/// @endcond
+
 // ---- Operators defined in index space
 
 

openvdb/openvdb/points/IndexFilter.h

@@ -63,7 +63,7 @@ namespace points {
 
 ////////////////////////////////////////
 
-
+/// @cond OPENVDB_DOCS_INTERNAL
 
 namespace index_filter_internal {
 
@@ -97,6 +97,8 @@ generateRandomSubset(const unsigned int seed, const IntType n, const IntType m)
 
 } // namespace index_filter_internal
 
+/// @endcond
+
 
 /// Index filtering on active / inactive state of host voxel
 template <bool On>