On the documentation of pseudomodules

[leandrolanzieri]

I have a question regarding the documentation of pseudomodules (triggered by an error in #21985). According to the PR that introduced documenting pseudomodules (#17133) "A dedicated group is created for each module.", but there seems to be some inconsistencies in pseudomodules.inc.mk (I think).

This one defines a group for gnrc_nettype_ccn and sets net_gnrc_nettype as a parent:

RIOT/makefiles/pseudomodules.inc.mk

Lines 137 to 144 in f442d25

	## @addtogroup net_gnrc_nettype
	## @{
	## @defgroup net_gnrc_nettype_ccn gnrc_nettype_ccn
	## @{
	## Enables @ref GNRC_NETTYPE_CCN and @ref GNRC_NETTYPE_CCN_CHUNK
	PSEUDOMODULES += gnrc_nettype_ccn
	## @}

This has the effect that now gnrc_nettype: Protocol type shows up as a child of Generic pseudomodules, but at least we know that gnrc_nettype_ccn will enable the GNRC implementation of CCN (though the location of this information may be questionable).

Conversely, we have this example:

RIOT/makefiles/pseudomodules.inc.mk

Lines 87 to 93 in f442d25

	## @addtogroup net_gcoap_dns
	## @{
	## Enable @ref net_gcoap_dns
	PSEUDOMODULES += gcoap_dns
	## Enable the @ref gcoap_dns_server_proxy_set function
	PSEUDOMODULES += gcoap_dns_proxied
	## @}

In this case we have the same effect of the GCoap DNS module being a child of pseudomodules. One can argue that this is correct in this case. But the documentation now just shows an extra sentence in the module's page, with no clue as to which pseudomodule is required, and it even has a circular reference: https://doc.riot-os.org/group__net__gcoap__dns.html.

What should be the (documented) approach to this?
Some quick thoughts:

1. We could simple define always a doxygen group with pseudomodule_ prefix or so, and make it a child of the proper module (maybe using ingroup instead of addtogroup?).
2. We could skip defining groups whenever one direct matching already exists, but define the rest.

I'd say that whatever option we go with, the @brief and / or title should explicitly mention the pseudomodule, otherwise one doesn't gain much from just reading the docs.

CC @chrysn

[carl-tud]

Generally, I believe, there ought to be a dedicated group for each module, no matter whether it's a pseudomodule or not because, as a user of RIOT, you shouldn't need to how something was implemented, and the fact that a module doesn't correspond to a physical file is an implementation detail, IMO. If that's the case and you do need to know, then the API should look differently in that it shouldn't make you care either.

Our second problem is that we have no control over how and if the role of certain entities (boards, modules, and _pseudo_modules, if you want) are represented in the documentation. I strongly believe this role must not be expressed structurally, i.e., there shouldn't be groups just for the sake of expressing a property of all subgroups.
Rather a characteristic like that may perhaps be displayed on each module page, such as with an alias @riotpseudomodule that turns into a small admonition "fyi, this is a pseudomodule".
So, I think the generic pseudomodules group should not exist -- as should a group all modules not exist. It may be fine to have a group of all boards or CPUs, but only if that's the major distinguishing factor. For pseudomodules, the "pseudo" property is not a key distinguishing factor. Something like net_gnrc_nettype as a parent for the submodules seems like a good idea since the procotol type could be a good key distinguishing aspect.

(Following this logic, we should ask ourselves if it makes sense to have all compile-time configurations be children of a generic "Compile-Time Configurations" group. Perhaps it does not at all.).

Don't get me wrong, we can still make pseudomodules members of a another "pseudomodules" group as a helpful place to look them all up, as long as that doesn't constitute ownership of the "pseudomodules" group over all pseudomodules inside, i.e., once you click on an pseudomodule in the "pseudomodules" group, you should get redirected to wherever this submodule is really located, as explained before. But, I am unsure if we can reliably tell doxygen what membership we consider "primary" aka. differentiate between "ownership" and plain "membership".

After all, that pseudomodules group only exists because one cannot easily search for all pseudomodules. So it's kind of a materialised or static search query and perhaps a symptom of the rather dysfunctional search functionality. (Still, you can justify having a group of things it doesn't own, if people frequently look it up (but that's a judgement call)).

Next problem: Right now, we cannot assign custom symbols to a group (because we use "group" as a catch-all for entities there is no native documentation support for: boards, cpus, modules, ...). A symbol for a module would be something like import|use|whatever fancy_module, or in RIOT USEMODULE += fancy_module, akin to a function signature or prototype of a function entity, that tells you how to use the thing you're looking at, it's an instruction. The documentation page for a CoAP endpoint would probably show you some GET coap://host.tld/ascii-art/cows URI as a symbol, because that gives you a rough idea of what this is and what action you can take. That's what the pseudomodule file is trying to do with the @{ and @} around each PSEUDOMODULES += ..., yet it doesn't work, at least at the moment; and doesn't make sense even if the PSEUDOMODULES += ... line would turn up it the docs: again, what does PSEUDOMODULES += ... tell you as a RIOT user? Well, nothing actionable. USEMODULE += ... would, but that is more of a problem of all modules we have, and not really core to this discussion.

Final problem: The textual description is often times missing from our documentation and, most importantly, does not explain acronyms and what things really do to a RIOT newbie:

gnrc_nettype_ccn

Enables GNRC_NETTYPE_CCN and GNRC_NETTYPE_CCN_CHUNK.

What is CCN? What action can I perform on gnrc_nettype_ccn? I know it's a pseudomodule, so the action would be to import it in the application makefile, but that page makes in no way obvious. Why does whatever I am looking at 'enable' two enum cases? Maybe it's also worth debating if 'enabling' something here is the right choice of words. I can enable an enum case, by using it in a bitfield, or by passing it to some function; but what I think is actually meant here is that gnrc_nettype_ccn allows you to use that enum case, it enables you to use them.

This is what each entry should look like:

@defgroup net_gnrc_nettype_ccn Support for Cool Color Networking Protocol (CCN) in GNRC (side note: this lives in the GNRC group, so that abbreviation should be fine)
@ingroup net_gnrc_nettype
@brief Allows using @ref GNRC_NETTYPE_CCN and @ref GNRC_NETTYPE_CCN_CHUNK protocol types in abc and xyz APIs
@riotpseudomodule
@{ 
Optional more detailed description of what tht module does
@}

or

@addtogroup net_gnrc_nettype
@{

@defgroup net_gnrc_nettype_ccn Support for Cool Color Networking Protocol in GNRC (side note: this lives in the GNRC group, so that abbreviation should be fine)
@brief Allows using @ref GNRC_NETTYPE_CCN and @ref GNRC_NETTYPE_CCN_CHUNK in abc and xyz APIs
@riotpseudomodule
@{ 
Optional more detailed description of what tht module does
@}

... more nettype modules

@}

(perhaps @riotpseudomodule must go into the @{ -enclosed part, idk.)
In doxyfile: ALIASES += "riotpseudomodule=@remark This is a pseudomodule, so it does not correspond to a file. You can still treat it like a regular module. [Read more about modules in ...](#)"

When more extensible documentation tooling turns up sometime, we can leverage custom directives like riotpseudomodule as a data source for search filters, completely eliminating the need for a nice-place-to-look-up all-pseudomodules group. Although, as mentioned above, when it would come in handy to have a go-to group that doesn't own its members (essentially for a common search query, such as all submodules or all compile-time configurations), we could even automate the creation of such a group, so one wouldn't need to expressly state membership each time.