Re: Doxygen Tidy-up

[Christian Grothoff]

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
>>>
>>>
>>
>>
>