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