Identify Broken Links and Reference Errors
Begin by running Doxygen to generate the documentation. If there are broken links or reference errors, Doxygen typically reports them in the console output. Look for warnings like unable to resolve reference or link could not be resolved.
Check the generated doxygen.log file in the output directory (if logging is enabled) for a detailed list of errors and warnings.
Review Your Doxyfile Settings
Ensure that your INPUT paths are correct. Misconfigured paths can cause Doxygen to miss files, which leads to broken references. Double-check all relative and absolute paths in your Doxyfile.
Make sure that the EXTRACT_ALL tag is set to YES. This setting ensures that even undocumented entities are included, which could resolve missing references.
Verify that RECURSIVE is set to YES if your source code is structured in subdirectories. Failing to do so might cause Doxygen to skip files.
Check Your Code Annotations
Ensure that all references in your comments and documentation blocks use the correct syntax. For example, references to functions, enums, macros, etc., should be wrapped in @ref tags. Example:
```c
/**
This function is a wrapper for the @ref my_function.
*/
void another_function();
```
If you're linking to specific pages or sections, ensure that you've declared those sections with @page or other structuring commands.
Address External References
If linking to external documentation, ensure the TAGFILES setting in the Doxyfile is correct. It should point to a valid .tag file, which Doxygen uses to resolve external symbols.
Make sure the paths to external documentation or files are correct and accessible. Broken links often result from incorrect paths.
Use Aliases and Custom Commands Carefully
If you use custom commands or aliases (via ALIASES in your Doxyfile), make sure these don't inadvertently create unresolved references. Misconfigured aliases can result in broken links.
Check any included files or templates to ensure they generate correct references. Problems in commonly included headers can propagate errors that appear widespread.
Re-generate and Validate Documentation
After resolving all identified issues, re-run Doxygen and generate the documentation anew. Evaluate the console output for any remaining errors.
Conduct a manual spot check of the generated HTML documentation to ensure links are functioning as expected. Navigate through some of the key references and cross-links for verification.
Use Version Control / Automated Builds
Incorporate Doxygen generation in your CI/CD pipeline. Automated builds ensure documentation is consistently generated and any new issues or broken links are caught early.
Use version control diff tools to track changes in documentation comments, helping to identify when a reference or link was broken.
By carefully going through these steps, you can ensure that your Doxygen-generated firmware documentation is free of broken links and reference errors, maintaining comprehensive and accessible documentation for your projects.
