sys: add modulenames for Doxygen

[kfessel]

Contribution description

Add modulenames for Doxygen

Testing procedure

read the murdoc doxygen prview

Issues/PRs references

#7094
#8479

[benpicco]

The Department of Redundancy Department would approve, but I don't see how this makes anything better.
Our documentation already suffers from duplication in @defgroup and @brief which just looks odd when rendered, we don't need triplication.

[riot-ci]

Murdock results

✔️ PASSED

f67bb8c doccheck updated

Success	Failures	Total	Runtime
1	0	1	56s

Artifacts

• Documentation preview

[kfessel]

I do not see a cononical place the module name is rendered to in our current documentation

Callback multiplexer

Initialization of USB Device Firmware < the title of that page not even contains a hint that it might be conneted to riotboot

Millisecond interval event timers << what module is this?

for UDP benchmark is it USEMODULE += udp_benchmark or benchmark_udp

[maribu]

I do not see a cononical place the module name is rendered to in our current documentation

It is indeed an issue that students regularly express. Specifically, they find some function in the doc but don't know which module to include to be able to use it.

But IMO the KConfig files would be the place to generate a list of module names from, especially as they already have a brief description / help text already. Maybe that could be used to generate a doc.txt from automatically?

It would be a huge pain to keep the KConfig module description, the @brief and @defgroup, as well as a third registry in sync.

[kfessel]

Some auto generation would be nice but sadly the the current situation is realy bad the @defgroups are allover the place and are of very different quality, often the group names correlate with the module name but not always somtimes the title hints the module name, sometimes it just has the word reversed sometimes for good sometimes it seems the writer just did not want to write his chosen modulename and have some extra fun with words.

"Helpers for pointer tagging" is what module?

[benpicco]

A lot of those aren't actually modules - is this intentional?

[benpicco]

memory_management is not a module

[benpicco]

serialization is not a module

[benpicco]

lorawan is not a module

[benpicco]

ecc is not a module

[benpicco]

architecture is not a module

[kfessel]

This module provides architecture-independent access to architecture details.

There seems to be a bit of clarity missing when something is a module and when not. (Is a module that is not need to be used a module?)

[OlegHahm]

I still like the proposal from the last VMA to add a usage section that includes information about which module to use (and which header to include).

[kfessel]

I still like the proposal from the last VMA to add a usage section that includes information about which module to use (and which header to include).

I also like that proposal, sadly that takes much longer to implement, since when doing that it would be a module by module effort and would for many module require a person that has some inside knowlege about that module.

I think having the area of concern (like we do for our pr) in the title of the documentation is a huge step;
For modules it is the generalized and standardized modul-name.
For packages it is the generalized and standardized package-name.
(eg for flashdb it would be flashdb not FlashDB, not flashdb-mtd)
For boards it is the standardized board-name.

standardized: lowercase like we write in pr , usemodule / usepackage.

@benpicco: the area of concern is also the reason why some not modules got a generalized and standardized name.

[OlegHahm]

I still like the proposal from the last VMA to add a usage section that includes information about which module to use (and which header to include).

I also like that proposal, sadly that takes much longer to implement, since when doing that it would be a module by module effort and would for many module require a person that has some inside knowlege about that module.

Understood but as far as I understood your approach here also requires manual maintenance or am I mistaken? On the other hand, why not go step by step? Maybe we setup a bit tracking issue and try to introduce these usage sections one by one?