Merge pull request #1092 from Idclip/doc_improvements

Doxygen Improvements

Author: Idclip

CHANGES

@@ -1548,8 +1548,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.

ci/extract_test_examples.sh

@@ -52,13 +52,13 @@ for DOC in "${DOCS[@]}"; do
         elif [[ $line == @code* ]]; then
             str=""
             compile="none"
-        elif [[ $line == "<!--- V --->@code"* ]]; then
+        elif [[ $line == "<!-- V -->@code"* ]]; then
             str=""
             compile="volumes"
-        elif [[ $line == "<!--- P --->@code"* ]]; then
+        elif [[ $line == "<!-- P -->@code"* ]]; then
             str=""
             compile="points"
-        elif [[ $line == "<!--- A --->@code"* ]]; then
+        elif [[ $line == "<!-- A -->@code"* ]]; then
             str=""
             compile=""
         elif [[ $line == @endcode ]]; then

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,36 @@ 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)
+set(DOXYGEN_STRIP_FROM_PATH
+  "${CMAKE_SOURCE_DIR}/openvdb"
+  "${CMAKE_SOURCE_DIR}/openvdb_ax"
+  "${CMAKE_SOURCE_DIR}/openvdb_houdini"
+  "${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>)"]]
@@ -115,8 +138,19 @@ set(DOXYGEN_PREDEFINED
   "OPENVDB_VERSION_NAME=v${OpenVDB_MAJOR_VERSION}_${OpenVDB_MINOR_VERSION}"
   "OPENVDB_ABI_VERSION_NUMBER=${OpenVDB_MAJOR_VERSION}"
   [[__declspec(x):= __attribute__(x):=]]
+  # Replace the deprecated macros with doxygen deprecated comments. This ensures
+  # that every bit of deprecated C++ is listed in the doxygen deprecated list,
+  # even if it was not properly tagged
+  [["OPENVDB_DEPRECATED=/** \deprecated */"]]
+  [["OPENVDB_DEPRECATED_MESSAGE(x)=/** \deprecated 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)