View Issue Details

Jump to NotesJump to History
IDProjectCategoryView StatusDate SubmittedLast Update
0007314GNUnetdocumentationpublic2022-08-28 19:472022-08-28 22:59
Reporterwillow Assigned To 
PrioritynormalSeverityminorReproducibilityalways
Status newResolutionopen 
Summary0007314: Doxygen Cleanup: Widespread redundant documentation
DescriptionOur Doxygen source code documentation, while extensive, generates a veritable flood of warnings that have accumulated from years of lax maintenance. The overwhelming majority of the warnings are about redundantly-documented parameters, due to the (now abandoned) practice of documenting symbols in both the source and the header.

These not only clutter stderr when you build the docs, but also increase the maintenance load of the documentation, and make it harder to spot more serious issues.

I've written a python script (contrib/warningfilter.py), recently pushed to origin, that can filter these warnings into easily-read reports. These can be reduced and sorted with simple shell programs. My practice for the redundant comments has been to pipe the output through tail -n +2| sort -u -k 4 | sort -k 1 to remove the title line, deduplicate symbol names, and then sort by filename. I have made use of this, along with some simple vimscript and macros, to deal with roughly 1200 "multiple @param doc" warnings over the last few days.

Anyone should be able to pitch in with the cleanup now, but to avoid duplicated effort we should coordinate which sections of the source tree we tackle. Going alphabetically, I've already conducted a first pass through everything that came up, up to src/include/gnunet_dnsparser.h.

As I understand, doc comments should be located with a function's declaration.
Tagschore, low hanging fruit

Activities

willow

2022-08-28 22:59

developer   ~0019067

Here's the most recent list of symbols with duplicate docs, produced by the warning filtration process.
dup-params (51,394 bytes)   

Issue History

Date Modified Username Field Change
2022-08-28 19:47 willow New Issue
2022-08-28 19:47 willow Tag Attached: chore
2022-08-28 19:47 willow Tag Attached: low hanging fruit
2022-08-28 19:48 willow Description Updated
2022-08-28 22:59 willow Note Added: 0019067
2022-08-28 22:59 willow File Added: dup-params