Fix #1378, 1589, doxygen cleanup

cmake/arch_build.cmake

@@ -611,21 +611,11 @@ function(process_arch SYSVAR)
   # This can help with debugging if things go wrong.
   message(STATUS "PSP Selection: ${CFE_SYSTEM_PSPNAME}")
 
-  # Append the PSP and OSAL selections to the Doxyfile so it will be included
-  # in the generated documentation automatically.
-  # Also extract the "-D" options within CFLAGS and inform Doxygen about these
-  string(REGEX MATCHALL "-D[A-Za-z0-9_=]+" DOXYGEN_DEFINED_MACROS "${CMAKE_C_FLAGS}")
-  string(REGEX REPLACE "-D" " " DOXYGEN_DEFINED_MACROS "${DOXYGEN_DEFINED_MACROS}")
-  file(APPEND "${MISSION_BINARY_DIR}/doc/mission-content.doxyfile"
-    "PREDEFINED += ${DOXYGEN_DEFINED_MACROS}\n"
-    "INPUT += ${MISSION_SOURCE_DIR}/osal/src/os/${OSAL_SYSTEM_OSTYPE}\n"
-    "INPUT += ${MISSION_SOURCE_DIR}/psp/fsw/${CFE_SYSTEM_PSPNAME}\n"
-    "INPUT += ${CMAKE_BINARY_DIR}/inc")
-
-  # Append to usersguide.doxyfile
-  file(APPEND "${MISSION_BINARY_DIR}/doc/cfe-usersguide.doxyfile"
-    "INPUT += ${MISSION_SOURCE_DIR}/psp/fsw/${CFE_SYSTEM_PSPNAME}/src\n"
-    "INPUT += ${CMAKE_BINARY_DIR}/inc")
+  # Create a documentation content file, with any system-specific doxygen info
+  # this is done here in arch_build where the CFE_SYSTEM_PSPNAME is known
+  file(WRITE "${MISSION_BINARY_DIR}/doc/tgtsystem-content-${SYSVAR}.doxyfile"
+    "INPUT += ${CMAKE_BINARY_DIR}/inc\n"
+  )
 
   # The PSP and/or OSAL should have defined where to install the binaries.
   # If not, just install them in /cf as a default (this can be modified

cmake/cfe-common.doxyfile.in

@@ -2,7 +2,6 @@
 # Project related configuration options, shared for all cFE doxygen outputs
 #---------------------------------------------------------------------------
 @INCLUDE_PATH          = @MISSION_SOURCE_DIR@
-OUTPUT_DIRECTORY       = .
 ABBREVIATE_BRIEF       = "The $name class " \
                          "The $name widget " \
                          "The $name file " \
@@ -55,7 +54,6 @@ GENERATE_DEPRECATEDLIST= YES
 # configuration options related to warning and progress messages
 #---------------------------------------------------------------------------
 WARN_NO_PARAMDOC       = YES
-WARN_LOGFILE           = @CMAKE_BINARY_DIR@/doc/warnings.log
 #---------------------------------------------------------------------------
 # configuration options related to the input files
 #---------------------------------------------------------------------------
@@ -77,6 +75,12 @@ INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/cfe_xref.dox
 FILE_PATTERNS          = *.c *.cpp *.cc *.C *.h *.hh *.hpp *.H *.dox *.md
 RECURSIVE              = YES
 EXAMPLE_PATTERNS       = *
+
+# Exclude coverage tests, stubs and associated framework from the documentation
+EXCLUDE_PATTERNS       += "*/ut-stubs/*"
+EXCLUDE_PATTERNS       += "*/ut-coverage/*"
+EXCLUDE_PATTERNS       += "*/unit-test*/*"
+
 #---------------------------------------------------------------------------
 # configuration options related to source browsing
 #---------------------------------------------------------------------------

cmake/cfe-usersguide.doxyfile.in

@@ -8,7 +8,8 @@ INPUT                 += @MISSION_SOURCE_DIR@/cfe/docs/src/main.dox
 # Common definitions, some of which are extended or overridden here.
 @INCLUDE               = @MISSION_BINARY_DIR@/doc/cfe-common.doxyfile
 PROJECT_NAME           = "Core Flight Executive Users Guide"
-OUTPUT_DIRECTORY       = users_guide
+OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/doc/users_guide
+WARN_LOGFILE           = @CMAKE_BINARY_DIR@/doc/cfe-usersguide-warnings.log
 GENERATE_LATEX         = YES
 
 # For purposes of the user guide, reference the "stock" mission configuration
@@ -17,7 +18,6 @@ GENERATE_LATEX         = YES
 STRIP_FROM_PATH       += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs
 INPUT                 += @MISSION_SOURCE_DIR@/cfe/cmake/sample_defs
 
-#PREDEFINED
 PREDEFINED            += @USERGUIDE_PREDEFINED@
 
 # Bring in the cFE header files for the documentation of the various API calls

cmake/mission-detaildesign.doxyfile.in

@@ -6,28 +6,14 @@
 @INCLUDE               = @MISSION_BINARY_DIR@/doc/cfe-common.doxyfile
 PROJECT_NAME           = "@MISSION_NAME@"
 PROJECT_BRIEF          = "Core Flight System project built using \"@MISSIONCONFIG@\" configuration"
-OUTPUT_DIRECTORY       = detaildesign
-
-INPUT                 += @MISSION_DEFS@  \
-                         @MISSION_SOURCE_DIR@/osal/src/os/inc \
-                         @MISSION_SOURCE_DIR@/osal/src/os/shared \
-                         @MISSION_SOURCE_DIR@/psp/fsw/inc \
-                         @MISSION_SOURCE_DIR@/psp/fsw/shared \
-                         @MISSION_SOURCE_DIR@/cfe/modules/core_api/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/core_private/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/es/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/evs/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/fs/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/msg/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/resourceid/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/sb/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/sbr/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/tbl/fsw \
-                         @MISSION_SOURCE_DIR@/cfe/modules/time/fsw
+OUTPUT_DIRECTORY       = @CMAKE_BINARY_DIR@/doc/detaildesign
+WARN_LOGFILE           = @CMAKE_BINARY_DIR@/doc/detaildesign-warnings.log
 
+INPUT                 += @MISSION_DEFS@
 STRIP_FROM_PATH       += @MISSION_DEFS@
 
 #---------------------------------------------------------------------------
 # The user content doxyfile contains paths to the mission-specific applications
 #---------------------------------------------------------------------------
-@INCLUDE               = @CMAKE_BINARY_DIR@/doc/mission-content.doxyfile
+@DETAILDESIGN_DOXYFILE_USER_CONTENT@
+@TGTSYSTEM_DOXYFILE_USER_CONTENT@

cmake/mission_build.cmake

@@ -241,36 +241,58 @@ function(prepare)
   # If the user has provided a "Doxyfile" in their top level documentation directory,
   # then assume they have also set PROJECT_NAME and PROJECT_BRIEF in that.
   # Otherwise, generate reasonable strings for these values.
-  set(MISSION_DOXYFILE_USER_CONTENT)
+  set(DETAILDESIGN_DOXYFILE_USER_CONTENT)
   if (EXISTS "${MISSION_SOURCE_DIR}/doc/Doxyfile")
-    list(APPEND MISSION_DOXYFILE_USER_CONTENT "@INCLUDE = ${MISSION_SOURCE_DIR}/doc/Doxyfile\n")
+    list(APPEND DETAILDESIGN_DOXYFILE_USER_CONTENT "@INCLUDE = ${MISSION_SOURCE_DIR}/doc/Doxyfile\n")
   endif (EXISTS "${MISSION_SOURCE_DIR}/doc/Doxyfile")
 
+  # Add any detail design information from each app/module
   foreach(APP ${MISSION_DEPS})
-    # OSAL is handled specially, as only part of it is used
-    if (NOT APP STREQUAL "osal")
-      if (EXISTS "${${APP}_MISSION_DIR}/docs/${APP}.doxyfile.in")
-        # If the module provides its own doxyfile, then include it directly
-        # This allows for app-specific fine-tuning of the sources, based on its own source tree
-        configure_file("${${APP}_MISSION_DIR}/docs/${APP}.doxyfile.in"
-            "${CMAKE_BINARY_DIR}/doc/${APP}.doxyfile")
-        list(APPEND MISSION_DOXYFILE_USER_CONTENT "@INCLUDE = ${CMAKE_BINARY_DIR}/doc/${APP}.doxyfile\n")
-      else()
-        # Otherwise just add this entire directory to the "INPUT" list
-        list(APPEND MISSION_DOXYFILE_USER_CONTENT "INPUT += ${${APP}_MISSION_DIR}\n")
-      endif()
+
+    # There is some historical inconsistency in whether submodules have documentation
+    # in a "docs" or "doc" subdirectory.  Most GSFC CFS apps now use "docs" but OSAL
+    # had traditionally been "doc".  For best compatibility, either will be accepted/used.
+    # if no documentation dir is found, then just look for doxyfiles in the app dir
+    if (IS_DIRECTORY "${${APP}_MISSION_DIR}/docs")
+        set(APP_DOC_DIR "${${APP}_MISSION_DIR}/docs")
+    elseif(IS_DIRECTORY "${${APP}_MISSION_DIR}/doc")
+        set(APP_DOC_DIR "${${APP}_MISSION_DIR}/doc")
+    else()
+        set(APP_DOC_DIR "${${APP}_MISSION_DIR}")
+    endif()
+
+    # Now add the app-specific documentation to the detail design input set.
+    # This depends on whether the app has provided any guidance on this.
+    # The "doxyfile.in" should provide specific directives for what to include.  If
+    # not specified, then the entire app source tree will be used as a catch-all.
+    if (EXISTS "${APP_DOC_DIR}/${APP}-detaildesign.doxyfile.in")
+
+      # a "doxyfile.in" is a template that should be passed through configure_file()
+      # (which will expand any variable refs) then the result of this is included in the doxyfile
+      configure_file("${APP_DOC_DIR}/${APP}-detaildesign.doxyfile.in"
+        "${CMAKE_BINARY_DIR}/doc/${APP}-detaildesign.doxyfile")
+
+      list(APPEND DETAILDESIGN_DOXYFILE_USER_CONTENT "@INCLUDE = ${CMAKE_BINARY_DIR}/doc/${APP}-detaildesign.doxyfile\n")
+    else()
+
+      # Otherwise just add this entire directory to the "INPUT" list
+      list(APPEND DETAILDESIGN_DOXYFILE_USER_CONTENT "INPUT += ${${APP}_MISSION_DIR}\n")
     endif()
+
   endforeach()
 
-  # In all cases it is assumed to include the CFE documentation as well (could be configurable?)
-  file(WRITE "${CMAKE_BINARY_DIR}/doc/mission-content.doxyfile"
-      ${MISSION_DOXYFILE_USER_CONTENT})
+  set(TGTSYSTEM_DOXYFILE_USER_CONTENT)
+  foreach(SYSVAR ${TGTSYS_LIST})
+    list(APPEND TGTSYSTEM_DOXYFILE_USER_CONTENT "@INCLUDE = ${CMAKE_BINARY_DIR}/doc/tgtsystem-content-${SYSVAR}.doxyfile\n")
+  endforeach()
 
-  configure_file("${CFE_SOURCE_DIR}/cmake/cfe-common.doxyfile.in"
-    "${CMAKE_BINARY_DIR}/doc/cfe-common.doxyfile")
+  # Create single/unified strings from the lists
+  string(CONCAT DETAILDESIGN_DOXYFILE_USER_CONTENT ${DETAILDESIGN_DOXYFILE_USER_CONTENT})
+  string(CONCAT TGTSYSTEM_DOXYFILE_USER_CONTENT ${TGTSYSTEM_DOXYFILE_USER_CONTENT})
 
-  configure_file("${CFE_SOURCE_DIR}/cmake/mission-detaildesign.doxyfile.in"
-    "${CMAKE_BINARY_DIR}/doc/mission-detaildesign.doxyfile")
+  configure_file("${CFE_SOURCE_DIR}/cmake/cfe-common.doxyfile.in"
+    "${CMAKE_BINARY_DIR}/doc/cfe-common.doxyfile"
+    @ONLY)
 
   # Generate an "empty" osconfig.h file for doxygen purposes
   # this does not have the actual user-defined values, but will
@@ -295,16 +317,21 @@ function(prepare)
 
   string(REPLACE ";" " \\\n" MISSION_USERGUIDE_HEADERFILES "${MISSION_USERGUIDE_HEADERFILES}")
 
-  configure_file("${CFE_SOURCE_DIR}/cmake/cfe-usersguide.doxyfile.in"
-    "${CMAKE_BINARY_DIR}/doc/cfe-usersguide.doxyfile")
-
-  add_custom_target(mission-doc
-    doxygen mission-detaildesign.doxyfile
-    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc")
+  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/doc/detaildesign")
+  configure_file("${CFE_SOURCE_DIR}/cmake/mission-detaildesign.doxyfile.in"
+    "${CMAKE_BINARY_DIR}/doc/detaildesign/Doxyfile"
+    @ONLY)
+  add_custom_target(mission-doc doxygen
+    COMMAND echo "Detail Design: file://${CMAKE_BINARY_DIR}/doc/detaildesign/html/index.html"
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc/detaildesign")
 
-  add_custom_target(cfe-usersguide
-    doxygen cfe-usersguide.doxyfile
-    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc")
+  file(MAKE_DIRECTORY "${CMAKE_BINARY_DIR}/doc/users_guide")
+  configure_file("${CFE_SOURCE_DIR}/cmake/cfe-usersguide.doxyfile.in"
+    "${CMAKE_BINARY_DIR}/doc/users_guide/Doxyfile"
+    @ONLY)
+  add_custom_target(cfe-usersguide doxygen
+    COMMAND echo "Users Guide: file://${CMAKE_BINARY_DIR}/doc/users_guide/html/index.html"
+    WORKING_DIRECTORY "${CMAKE_BINARY_DIR}/doc/users_guide")
 
   # OSAL API GUIDE include PUBLIC API
   set(OSAL_API_INCLUDE_DIRECTORIES