Feature: <module_info> in info.txt files

[reneme]

This is to improve on my previous draft PR and split things up a little.

<module_info>

I added <module_info> tags to all info.txt module descriptions along with the necessary parsing code in configure.py.

<module_info> contains three variables:

• name -- a human-friendly name for the module
• brief -- a short description of the module's content (optional)
• type -- the type of the module (Public, Internal or Virtual) (defaults to Public)

Note that new modules are rejected if they do not contain a <module_info> tag that specify the name variable at least.

<module_info> \n type -> "..."

This introduces module types (inspired by a previous discussion in the initial Kyber PR), to define a module's visibility and library user interaction.

Public modules behave like the current modules. They usually contain some implementation files, may or may not contain sub-modules, can be depended upon or depend on other modules and can be enables/disables at build time by the library user.

Internal modules behave essentially like Public modules, but the library user cannot actively enable/disable them. They are supposed to contain code that shouldn't be interacted with directly by the library user. Frankly, I don't know of any such module apart from the recently introduced kyber_common.

Virtual modules essentially tackle the first limitation stated in the previous PR. They can be seen as "Internal" but must not contain implementation files and cannot be depended upon. Instead they are meant as container modules to other (Public) modules. Examples are: prov, math, misc, passhash each containing sub-modules. We require them as a location to place the <module_info> for those "container directories".

[codecov-commenter]

Codecov Report

Merging #3032 (cb50c8a) into master (120ab62) will decrease coverage by 0.00%. The diff coverage is n/a.

@@            Coverage Diff             @@
##           master    #3032      +/-   ##
==========================================
- Coverage   92.62%   92.61%   -0.01%     
==========================================
  Files         596      596              
  Lines       69779    69779              
  Branches     6616     6616              
==========================================
- Hits        64632    64627       -5     
- Misses       5114     5119       +5     
  Partials       33       33              

Impacted Files	Coverage Δ
src/lib/utils/thread_utils/semaphore.cpp	69.23% <0.00%> (-30.77%)	:arrow_down:
src/lib/asn1/der_enc.cpp	83.85% <0.00%> (-2.49%)	:arrow_down:
src/lib/tls/tls12/tls_channel_impl_12.cpp	89.33% <0.00%> (+0.28%)	:arrow_up:
src/lib/asn1/asn1_obj.cpp	96.49% <0.00%> (+1.75%)	:arrow_up:

Help us with your feedback. Take ten seconds to tell us how you rate us. Have a feature suggestion? Share it here.

[randombit]

Can you explain more about the reasoning for the virtual modules? I would have thought of say math/ is just a plain directory which happens to contain some more module directories within it, but not of it being as a module of any kind itself.

[reneme]

I wanted a way to group the math modules together in the documentation. Otherwise they would have showed up top-level in the Doxygen module list. Now there's a "virtual" module with some documentation @brief combining them.

I.e. the "virtual" module idea is purely for documentation purposes.

Here's a screenshot from the former draft PR where "base**" and "hex" show up toplevel. In the new PR they are grouped under the "virtual" module "Codecs".

without "virtual" modules

with "virtual" modules