On 6/9/22 23:52, Willow Liquorice wrote:
I've categorised the code as much as I can, though I'm not too sure
about the function of some modules and I've only categorised within
src/include, so there's still a bit that's unsorted. It's mostly
services that are undocumented elsewhere, and libraries of uncertain
function that I couldn't establish as part of libgnunetutil.
I've also knocked a rudimentary script together, to process the literal
torrent of warnings Doxygen emits when I build the source docs. I've
used regexes to categorise them, and here are the results:
* 5655 occurrences of parameters with multiple docs across 175
source files.
* 3372 documented parameters which do not exist in their
corresponding function definitions, across 276 source files.
* 1660 functions with undocumented parameters, across 282 source
files.
* 760 explicit links to other parts of the documentation cannot be
resolved.
* 2-300 errors across a laundry list of other categories.
This is a rather sorry state of affairs.
Those redundant parameters reflect a common phenomenon in the
repository, where a function is documented in multiple locations. I'm
not sure about the reasons for doing this, but in my opinion it
unnecessarily increases the maintenance load as documentation has to be
updated in multiple locations.
Right, which is why for a few years we've been eliminating the
duplicates, always only keeping the version in the header if a function
is non-static. Alas, as you said above, there is a very large number of
these, and so progress is slow but steady.
I think a code style decision needs to be made, about where to locate
docs, and the redundant documentation removed.
Headers, otherwise (static prototypes) on first occurrence.
I've also found, in my experiments with the new Sphinx docs, that the
redundantly-documented parameters are counted twice by Breathe, which
could motivate stripping the redundant docs if we decide to go ahead
with integrating source code docs.
What do people think?
We've been doing this, but basically only whenever we edit a source file
already, due to, eh, "capacity" issues ;-).
Cheers!
Christian
On 06/06/2022 09:27, Martin Schanzenbach wrote:
Hi,
that sounds like a good approach to me :)
Thanks
Martin
On Sun, 2022-06-05 at 23:59 +0100, Willow Liquorice wrote:
Hello everyone,
I was going to mention this at the Dev Meeting today, but Mumble
wasn't
playing very nicely with my OS' audio system.
Another thing I've decided to work on is making the Doxygen site more
user-friendly, as I found out that it's possible to nest groups.
I've used this capability to make the Modules page easier to navigate
by
adding an layer or two of domain-specific grouping on top of the
current
modules (putting all the libgnunetutil headers into their own group,
the
network backbone going into one group, etc. etc.).
Does this sound like a good idea, and what would your recommendations
be
for how to organise the modules if so?
Best wishes,
Willow
0001-Doxygen-First-redundant-comment-stripping-results.patch