Doxygen documentation: more fixes and cleanups

chenbk85 · Dec 1, 2014 · 1523fdc · 1523fdc
1 parent f9a83c2
commit 1523fdc
Show file tree

Hide file tree

Showing 41 changed files with 894 additions and 859 deletions.
diff --git a/doc/CMakeLists.txt b/doc/CMakeLists.txt
@@ -146,43 +146,59 @@ if(BUILD_DOCS AND HAVE_SPHINX)
 endif()
 
 # ========= Doxygen docs =========
+
+macro(make_reference result modules_list black_list)
+    set(_res)
+    foreach(m ${${modules_list}})
+        list(FIND ${black_list} ${m} _pos)
+        if(${_pos} EQUAL -1)
+            set(_res "${_res} @ref ${m} | ${m} \n")
+        endif()
+    endforeach()
+    set(${result} ${_res})
+endmacro()
+
 if(BUILD_DOCS AND HAVE_DOXYGEN)
-  # documented modules list
-  set(candidates)
-  list(APPEND candidates ${BASE_MODULES} ${EXTRA_MODULES})
-  # blacklisted modules
-  ocv_list_filterout(candidates "^ts$")
+  # not documented modules list
+  list(APPEND blacklist "ts" "java" "python2" "python3" "world")
 
   # gathering headers
-  set(all_headers) # files and dirs to process
-  set(all_images) # image search paths
-  set(reflist) # modules reference
-  foreach(m ${candidates})
-    set(reflist "${reflist} \n- @subpage ${m}")
-
-    set(header_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/include")
-    if(EXISTS ${header_dir})
-        set(all_headers ${all_headers} ${header_dir})
-    endif()
-
-    set(docs_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/doc")
-    if(EXISTS ${docs_dir})
-      set(all_images ${all_images} ${docs_dir})
-      set(all_headers ${all_headers} ${docs_dir})
+  set(paths_include)
+  set(paths_doc)
+  set(paths_bib)
+  foreach(m ${BASE_MODULES} ${EXTRA_MODULES})
+    list(FIND blacklist ${m} _pos)
+    if(${_pos} EQUAL -1)
+      set(header_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/include")
+      if(EXISTS "${header_dir}")
+        list(APPEND paths_include "${header_dir}")
+      endif()
+      set(docs_dir "${OPENCV_MODULE_opencv_${m}_LOCATION}/doc")
+      if(EXISTS "${docs_dir}")
+        list(APPEND paths_doc "${docs_dir}")
+        file(GLOB bib_file "${docs_dir}" "*.bib")
+        if(EXISTS "${bib_file}")
+          list(APPEND paths_bib "${bib_file}")
+        endif()
+      endif()
     endif()
-
   endforeach()
 
+
   # additional config
   set(doxyfile "${CMAKE_CURRENT_BINARY_DIR}/Doxyfile")
   set(rootfile "${CMAKE_CURRENT_BINARY_DIR}/root.markdown")
-  set(all_headers ${all_headers} ${rootfile})
-  string(REGEX REPLACE ";" " \\\\\\n" CMAKE_DOXYGEN_INPUT_LIST "${all_headers}")
-  string(REGEX REPLACE ";" " \\\\\\n" CMAKE_DOXYGEN_IMAGE_PATH "${all_images}")
+  set(bibfile "${CMAKE_CURRENT_SOURCE_DIR}/opencv.bib")
+  string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_INPUT_LIST "${rootfile} ; ${paths_include} ; ${paths_doc}")
+  string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_IMAGE_PATH "${paths_doc}")
+  string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_EXAMPLE_PATH  "${CMAKE_SOURCE_DIR}/samples/cpp ; ${paths_doc}")
   set(CMAKE_DOXYGEN_LAYOUT "${CMAKE_CURRENT_SOURCE_DIR}/DoxygenLayout.xml")
   set(CMAKE_DOXYGEN_OUTPUT_PATH "doxygen")
-  set(CMAKE_DOXYGEN_MODULES_REFERENCE "${reflist}")
-  set(CMAKE_DOXYGEN_EXAMPLE_PATH "${CMAKE_SOURCE_DIR}/samples/cpp")
+  set(CMAKE_EXTRA_BIB_FILES "${bibfile} ${paths_bib}")
+
+  # generate references
+  make_reference(CMAKE_DOXYGEN_MAIN_REFERENCE BASE_MODULES blacklist)
+  make_reference(CMAKE_DOXYGEN_EXTRA_REFERENCE EXTRA_MODULES blacklist)
 
   # writing file
   configure_file(Doxyfile.in ${doxyfile} @ONLY)

diff --git a/doc/Doxyfile.in b/doc/Doxyfile.in
@@ -85,7 +85,7 @@ SHOW_FILES             = YES
 SHOW_NAMESPACES        = YES
 FILE_VERSION_FILTER    =
 LAYOUT_FILE            = @CMAKE_DOXYGEN_LAYOUT@
-CITE_BIB_FILES         = @CMAKE_CURRENT_SOURCE_DIR@/opencv.bib
+CITE_BIB_FILES         = @CMAKE_EXTRA_BIB_FILES@
 QUIET                  = YES
 WARNINGS               = YES
 WARN_IF_UNDOCUMENTED   = YES
@@ -222,6 +222,7 @@ INCLUDE_FILE_PATTERNS  =
 PREDEFINED             = __cplusplus=1 \
                          HAVE_IPP_A=1 \
                          CVAPI(x)=x \
+                         CV_DOXYGEN= \
                          CV_EXPORTS= \
                          CV_EXPORTS_W= \
                          CV_EXPORTS_W_SIMPLE= \

diff --git a/doc/root.markdown.in b/doc/root.markdown.in
@@ -3,9 +3,14 @@ OpenCV modules {#mainpage}
 
 @subpage intro
 
-Module name   | Folder
-------------- | -------------
-@ref core     | core
-@ref imgproc  | imgproc
+### Main modules
 
-<!-- @CMAKE_DOXYGEN_MODULES_REFERENCE@ -->
+ Module name   | Folder
+-------------- | -------------
+@CMAKE_DOXYGEN_MAIN_REFERENCE@
+
+### Extra modules
+
+ Module name   | Folder
+-------------- | -------------
+@CMAKE_DOXYGEN_EXTRA_REFERENCE@
diff --git a/modules/androidcamera/include/camera_activity.hpp b/modules/androidcamera/include/camera_activity.hpp
@@ -3,6 +3,12 @@
 
 #include <camera_properties.h>
 
+/** @defgroup androidcamera Android Camera Support
+*/
+
+//! @addtogroup androidcamera
+//! @{
+
 class CameraActivity
 {
 public:
@@ -44,4 +50,6 @@ class CameraActivity
     int frameHeight;
 };
 
+//! @}
+
 #endif
diff --git a/modules/androidcamera/include/camera_properties.h b/modules/androidcamera/include/camera_properties.h
@@ -1,6 +1,9 @@
 #ifndef CAMERA_PROPERTIES_H
 #define CAMERA_PROPERTIES_H
 
+//! @addtogroup androidcamera
+//! @{
+
 enum {
     ANDROID_CAMERA_PROPERTY_FRAMEWIDTH = 0,
     ANDROID_CAMERA_PROPERTY_FRAMEHEIGHT = 1,
@@ -67,4 +70,6 @@ enum {
     ANDROID_CAMERA_FOCUS_DISTANCE_FAR_INDEX
 };
 
+//! @}
+
 #endif // CAMERA_PROPERTIES_H