Documentation: Module Tree

[reneme]

Description

As a user of the library I often struggle with managing the available modules, especially when trying to select the ones to enable/disable.
Hence, this is a first step towards a more accessible module system by providing auto-generated documentation of the available modules, their inter-dependencies, platform requirements and contents.

For that, I added short documentation-friendly "module infos" to each module's info.txt file and rendered them into the Doxygen documentation as @defgroup tags.

For instance (AES-NI's info.txt):

<defines>
AES_NI -> 20131128
</defines>

<module_info>
name -> "AES-NI"
brief -> "AES using AES-NI and SIMD instructions"
</module_info>

<isa>
sse2
ssse3
aesni
</isa>

Potentially, the same information could be used to improve the UX of ./configure.py --list-modules and related configuration CUI features like error messages.

Demo

Here are some screenshots of the resulting Doxygen renderings:

Module Overview Page

This renders a tree-view of all modules and their sub-modules. Optionally, the module author can add a short description of the module's content. Note the new "Modules" main-menu entry that Doxygen automatically creates for this view.

Sub-Module Description Page

Each module is represented by a description page listing the contained source files and providing some extra information on the module: e.g. which other modules it depends on. Also note the bread crumbs describing the sub-module relationships.

Platform-specific Requirements

The platform-requirements (that are defined in the info.txt) can also be rendered into the detailed module description.

Limitations

Sub-Module Relationship

The module list is still fairly hard to grasp, I feel. Improving the grouping of specific modules might be really helpful here. For instance, create a "virtual" module for "codec" to group Base64, Base58 and Base32.

Also, the sub-module dependency is currently not detected for modules that reside in sub-sub-folders without an intermediate info.txt. For instance, the "Kyber" info.txt files are in pubkey/kyber/kyber_90s. But there is no info.txt at the pubkey/kyber level. As a result, Kyber 90s is currently treated as a top-level module. That might even cause functional bugs, as it probably breaks the implicit "parent modules are always required" assumption. Edit: e2ccb17 tacles that.

Assign APIs to Modules

It would be great if Doxygen could annotate APIs (classes, functions, enum, ...) to their respective module (or "group" in Doxygen-terms). Technically, we could do that manually, by annotating each item with the correct @ingroup ... tag, but that doesn't seem feasible.

As an example, I annotated Certificate_Store_MacOS resulting in the module bread-crumbs under the class' title as well as a list of contained APIs in the module description page.

It remains to be seen whether there is an automatic approach to that without auto-altering the header files.

Detailed Documentation

Currently, the info.txt <module_info> section doesn't provide a means to add more detailed descriptions for a specific module. Mainly, because I don't think it's desirable to add extensive text in there. If we'd want to add richer documentation to modules we'd need to see how those could be outsourced to dedicated documentation files.

RFC

What do you think about this attempt to improve the documenntation of Botans modules?

[codecov-commenter]

Codecov Report

Merging #3003 (efe2c7b) into master (987c7af) will increase coverage by 0.05%.
The diff coverage is n/a.

❗ Current head efe2c7b differs from pull request most recent head e2ccb17. Consider uploading reports for the commit e2ccb17 to get more accurate results

@@            Coverage Diff             @@
##           master    #3003      +/-   ##
==========================================
+ Coverage   92.57%   92.62%   +0.05%     
==========================================
  Files         596      596              
  Lines       69729    69729              
  Branches     6613     6613              
==========================================
+ Hits        64552    64588      +36     
+ Misses       5144     5108      -36     
  Partials       33       33              

Impacted Files	Coverage Δ
src/fuzzer/ressol.cpp	85.71% <0.00%> (-7.15%)	⬇️
src/fuzzer/mode_padding.cpp	93.65% <0.00%> (-6.35%)	⬇️
src/cli/entropy.cpp	83.33% <0.00%> (-4.77%)	⬇️
src/lib/misc/cryptobox/cryptobox.cpp	94.52% <0.00%> (-1.37%)	⬇️
src/lib/pubkey/dl_group/dl_group.cpp	92.63% <0.00%> (+1.05%)	⬆️
src/cli/cli_rng.cpp	80.76% <0.00%> (+5.76%)	⬆️
src/lib/pbkdf/argon2/argon2pwhash.cpp	84.50% <0.00%> (+7.04%)	⬆️
src/lib/utils/cpuid/cpuid_x86.cpp	88.31% <0.00%> (+14.28%)	⬆️
src/lib/utils/thread_utils/semaphore.cpp	100.00% <0.00%> (+30.76%)	⬆️
src/lib/entropy/rdseed/rdseed.cpp	100.00% <0.00%> (+78.26%)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 987c7af...e2ccb17. Read the comment docs.

[randombit]

I still need to review the code, but the concept is great and I would certainly encourage this kind of thing.

[reneme]

Superseded by #3032 and #3033.