Task #3210
closed
Fix doxygen errors and enable strict documentation check in Jenkins CI
100%
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.
Updated by Alex Afanasyev over 8 years ago
- Related to Task #3199: Enable clang's -Wdocumentation added
Updated by Alex Afanasyev over 8 years ago
- % 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)
Updated by Alex Afanasyev over 8 years ago
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.
Updated by Alex Afanasyev over 8 years ago
Example of the summary of doxygen errors by jenkins: http://jenkins.named-data.net/job/Doxygen-Checker/27/warnings13Result/new/
Updated by Davide Pesavento over 8 years ago
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.
Updated by Junxiao Shi over 8 years ago
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)?
Updated by Alex Afanasyev over 8 years ago
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.
Updated by Alex Afanasyev over 8 years ago
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.
Updated by Alex Afanasyev over 8 years ago
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?
Updated by Davide Pesavento over 8 years ago
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
Updated by Junxiao Shi over 8 years ago
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
Updated by Alex Afanasyev over 8 years ago
- Status changed from In Progress to Closed
- % Done changed from 50 to 100