Re: Doxygen Tidy-up

[Willow Liquorice]

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.

I think a code style decision needs to be made, about where to locate 
docs, and the redundant documentation removed.

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?

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