RIOT-OS
sys: add modulenames for Doxygen
Contribution description
Add modulenames for Doxygen
Testing procedure
read the murdoc doxygen prview
Issues/PRs references
#7094 #8479
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.
I do not see a cononical place the module name is rendered to in our current documentation
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
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.
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?
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 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.
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?