Re: Doxygen Tidy-up

[Christian Grothoff]

On 6/10/22 3:42 PM, Willow Liquorice wrote:
> Oh, I didn't know we already had a standard. I'll remember that and put
> it in the updated Style Guide.

:-)

> It's a good thing the team has a self-appointed documentation busybody
> now, hm?

A very good thing. ;-)

> Provided that the more recent docs are the ones in the headers,
> I'll have the source docs deduplicated by the end of next week.

That's largely a safe assumption, just make sure to NEVER remove
comments from 'static' functions. If the function has a very long
detailed comment, you may need to check that the header does indeed have
that comment and is not only an abbreviated version, but 95% of the time
they will be identical.

> Anyway, these are the modules that I'm unsure about how to categorise:
>     * "Load library"
>     * "CURL integration library"
>     * "NAT testing library"
>     * "MySQL library"
>     * "Friends library"
>     * "Credential service"
>     * "Resolver service"
>     * "Network type categorisation"
>     * "SOCKS proxy"
> 
> What do they do, and do any of these pertain to specific GNUnet subsystems?

MySQL (together with Postgres and Sqlite) are general helper functions
to talk to the respective database; they are often used with multiple
subsystems.

Load -- I think that's largely historic code to detect the current load
on the local system to allow FS (and theoretically other subsystems) to
adapt their behavior to system load.

CURL: generic http client logic

Resolver: generic DNS client logic

NAT testing/network type catgorization: helper subsystems for transport

Friends: parsing for 'topology' (gossip overlay / bootstrapping)

SOCKS: proxy logic for GNU Name System

Credential: GNS/Re:claimID.


> On 10/06/2022 07:04, Christian Grothoff wrote:
>> 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
>>>>>
>>>>>
>>>>
>>>>
>>>
>>
>

0x939E6BE1E29FC3CC.asc
Description: application/pgp-keys