Task #3210
closed
Fix doxygen errors and enable strict documentation check in Jenkins CI
Added by Alex Afanasyev over 8 years ago.
Updated over 8 years ago.
Description
We have a substantial amount of doxygen errors/warnings that we are mostly ignoring. We should fix these and to avoid making the same mistakes in the future, we should enable documentation build for every commit and fail the build process if there are warnings.
There are limitations on what doxygen understands. In complex cases we would need to add doxygen-specific workarounds. This will also help with documentation clarity. This can be achieved using DOXYGEN macro that is defined exclusively when doxygen is processing source code.
- Related to Task #3199: Enable clang's -Wdocumentation added
- % Done changed from 0 to 50
After playing with several jenkins plugins, I'm settling on the following configuration to test for doxygen documentation errors:
when a commit is submitted for review, jenkins will trigger two parallel jobs:
- primary job (e.g., ndn-cxx, NFD, ndns, NLSR)
- documentation checker (Doxygen-Checker)
failure of either job, results in Verified -1
either of the jobs can be independently retriggered, and gerrit status will be updated accordingly
Please comment, otherwise I will proceed with adding this check for other projects (for now, I have enabled it only for ndns)
For information purposes. I have tried to use Parametrized Trigger plugin (I was trying to run doxygen checks prior the main build, and prevent main build if there documentation errors). However, it had limitations for multi-configuration jobs and, I think, will not work for us.
Alex Afanasyev wrote:
Please comment, otherwise I will proceed with adding this check for other projects (for now, I have enabled it only for ndns)
Is the check currently passing for the other projects? If so, no objections from me.
What's the rationale of checking Doxygen in a separate job, instead of a step in the main job (similar to code coverage and standalone header compilation)?
About rationale: I couldn't find a way to "fail" doxygen. It seem to be producing warnings that I could find a way to convert to errors. Jenkins has a readily available plugin to process doxygen output and fail/pass based on number of warnings.
As for other other projects. I think checks are not yet passing. I can enable the new job in non-failing mode until all issues are fixed.
On another thought. I can add the following rudimentary warnings scanning script into .jenkins.d to check if there is any warning from doxygen output and fail if so:
./waf doxygen 3>&1 1>&2 2>&3 | tee warnings.txt
warnings=$(wc -l warnings.txt)
if [[ $warnings -ne 0 ]]; then
echo "Found $warnings doxygen warnings"
exit 1
fi
The jenkins plugin then can scan output for real and make html summary. Do you think it is a better approach?
Alex Afanasyev wrote:
As for other other projects. I think checks are not yet passing. I can enable the new job in non-failing mode until all issues are fixed.
OK
As Alex said on 20151015 conference call, Jenkins check would be non-fatal.
However, 2404,13 is marked Verified-1 solely due to the failure of Doxygen checker.
As agreed on 20151015 conference call, before switching to fatal mode, it's necessary to announce this to nfd-dev mailing list.
The announcement shall include:
- the date of requiring Doxygen check
- how to look for what failed on Jenkins (give an example)
- how to run Doxygen locally and determine whether it would fail on Jenkins prior to uploading the patchset
- (optional) common Doxygen mistakes
- Status changed from In Progress to Closed
- % Done changed from 50 to 100
Also available in: Atom
PDF
Updated by 
Updated by 
Updated by