doxygen warning: explicit link

[avan989]

Describe the bug
doxygen gives warning: explicit link request to 'CFE_SB_CmdHdr_t' could not be resolved ...etc

userguide_warning_explicit_link.txt

To Reproduce
Steps to reproduce the behavior:

1. make usersguide

System observed on:

• Hardware
• Ubuntu 18.04
• doxygen 1.8.13, rc-6.7-0

Reporter Info
Anh Van, NASA Goddard

[avan989]

Explicit link warning is caused by cross-referencing *.h files not being include in doxygen build.

For Example: CFE_SB_BufferD_t is being cross referenced by cfe/cmake/sample_defs/cpu1_platform_cfg.h but CFE_SB_BufferD_t is being defined src/sb/cfe_sb_priv.h which is not included in the doxygen build.

In addition some of the warning are given by struct being defined in several different PSP/OSAL. For example: CFE_PSP_ExceptionHook is being defined for linux, rtems, and mcp750-vxworks.

Possible Solution:

1. I get rid of all cross reference to get rid of these warning.

2. I include all the files in the build. But for this I would need to also implement logic in mission_build.cmake to choose the correct files based on the what psp/osal users choose.

[jphickey]

I think the solution choice is dependent on the context and probably needs to be evaluated on a case by case basis.

For instance the CFE_SB_BufferD_t is a private, CFE-internal data structure and not exposed in the public API. Therefore I would think this should also not be referenced in the "user guide" style API documentation.

However, if generating a CFE developers guide, then I would think all the internal files should be indexed in this case.

The problem of a developer guide is that the specifics are different for each CPU within a multi-CPU mission. So to be correct one would have to generate a separate dev guide for each of the CPUs within the mission. AFAIK the compromise here was just to build a single dev guide but potentially include more than one OSAL/PSP in it, and that is probably what triggers the warnings.

[skliper]

CCB 20191106 - discussed, with the forward path of just using the first target's configuration (OSAL and PSP) for default linkage where required. This is what CI will use (so linux/pc by default). Projects can always doxygen with a different configuration if they really want to, but by picking a default the warnings can be resolved.

edit - date