gnunet-developers
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Doxygen Tidy-up


From: Willow Liquorice
Subject: Re: Doxygen Tidy-up
Date: Thu, 9 Jun 2022 22:52:39 +0100
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:91.0) Gecko/20100101 Thunderbird/91.9.1

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







reply via email to

[Prev in Thread] Current Thread [Next in Thread]