RFC: include module name in doxygen documentation

[miri64]

I've come to realize that many new users struggle with what to include into their application and realized that while we have a good API documentation there is no specific information how to include a certain component. There is some general information about USEMODULE in the doc, but no information about what to add to USEMODULE if I want to include the e.g. net/gnrc/pktbuf.h in your project.

My proposal is that the first section of each module API doc should name the module(s) required for the functionality.

This is a lot of work so before I start it I would like your opinion on that.

[haukepetersen]

could you give a specific example for your proposal? But if I understand it correctly, I like this!

[miri64]

A simple example would be e.g. for xtimer

/*
 * @defgroup  sys_xtimer Timers
 * @ingroup   sys
 * @brief     Provides a high level timer module to register
 *            timers, get current system time, and let a thread sleep for
 *            a certain amount of time.
 *
 * # How to Use    << this title is totally up for discussion
 * To use this include the `xtimer` module to your application's Makefile:
 *
 * ~~~~~~~~~~~~~~~~~~~~~~ {.mk}
 * USEMODULE += xtimer
 * ~~~~~~~~~~~~~~~~~~~~~~
 *
 * ... (original sections)
 */

A more complex example e.g. with net/gnrc/ipv6.h:

/**
 * @defgroup    net_gnrc_ipv6 IPv6
 * @ingroup     net_gnrc
 * @brief       GNRC's IPv6 implementation
 *
 * # How to use
 * To use this include you need to add at minimum the `gnrc_ipv6` module to your
 * application's Makefile
 *
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.mk}
 * USEMODULE += gnrc_ipv6
 * ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 *
 * @ref pseudomodules that include `gnrc_ipv6` are:
 *
 * * `gnrc_ipv6_default`: pulls in `gnrc_ipv6` including host configuration of
 *   @ref net_gnrc_ndp
 * * `gnrc_ipv6_router_default`: pulls in `gnrc_ipv6` including router
 *   configuration of @ref net_gnrc_ndp and activates forwarding behavior
 * * ...
 *
 * ... (original sections)
 */

[smlng]

I like the idea - despite the additional work load 😉

Is it possible to put such extensive and detailed description in a separate file and link (reference) it into the docu via the header file? As far as I see, its already markdown syntax? If it is in a separate .md file it could also be compiled separately, without using doxygen.

[miri64]

Is it possible to put such extensive and detailed description in a separate file and link (reference) it into the docu via the header file? As far as I see, its already markdown syntax? If it is in a separate .md file it could also be compiled separately, without using doxygen.

No, and I would be against it. The doc should also be easily associatable in code (that's why we use Doxygen after all, otherwise we could just write some man pages ;-)).

[haukepetersen]

I think I like this as proposed. How about a simple Usage as section name?

[miri64]

How about a simple Usage as section name?

:+1:

[kaspar030]

While I like the "to use this, use module X", IMHO we should not repeat how to actually use a module. It would clutter the documentation a lot.

There's already documentation on how to use modules, which might need to be moved or improved.

[miri64]

There's already documentation on how to use modules, which might need to be moved or improved.

True, there are hyperlinks after all, so maybe

/*
 * @defgroup  sys_xtimer Timers
 * @ingroup   sys
 * @brief     Provides a high level timer module to register
 *            timers, get current system time, and let a thread sleep for
 *            a certain amount of time.
 *
 * # Usage
 * To use this component [include](@ref including-modules) the `xtimer` module.
 *
 * ... (original sections)
 */

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you want me to ignore this issue, please mark it with the "State: don't stale" label. Thank you for your contributions.

[miri64]

I still want this

[chrysn]

A similar style of documentation is already in use for USEPKG (not consistently, but eg. pkg/tinydtls/doc.txt has a Usage section like you suggest.

Is there a doxygen annotation with which to make he module name searchable? If, say, some application has USEMODULE += auto_init_saul, I can't find that term in doxygen. (I've tried various abuses for doxygen, but it doesn't look quite so simple). Anyway, I think we should have the modules in the documentation even if we can't easily find a solution to this detail.

[chrysn]

Next to modules, features should be documented the same way (possibly with the exception of periph features which have their associated modules).

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you want me to ignore this issue, please mark it with the "State: don't stale" label. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you want me to ignore this issue, please mark it with the "State: don't stale" label. Thank you for your contributions.

[stale[bot]]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. If you want me to ignore this issue, please mark it with the "State: don't stale" label. Thank you for your contributions.

[kfessel]

how about adding what is needed for USEMODULE just at the beginning of the title defined in defgroup like: 5x5 Font 'Mineplex' -> mineplex: 5x5 Font 'Mineplex' colorful logging -> log_color: colorful logging A minimal, non-destructive URI parser -> uri_parser: A minimal, non-destructive URI parser

or use a -

5x5 Font 'Mineplex' -> mineplex - 5x5 Font 'Mineplex' colorful logging -> log_color - colorful logging A minimal, non-destructive URI parser -> uri_parser - A minimal, non-destructive URI parser

[maribu]

Hell, yes! Like 80% of the questions I have to answer students in RIOT tutorials is what module a random function belongs to they found in the API doc.