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
