Configuration description of module

[knoepfel]

This issue has been migrated from https://cdcvs.fnal.gov/redmine/issues/17407 (FNAL account required) Originally created by @PetrilloAtWork on 2017-08-08 18:43:32

---

fhiclcpp offers automated validation and documentation of the configuration parameters. It would be good to have the same documentation possibility for the top level configuration object. For example:

struct Config {

  fhicl::Description desc{
    "The module estimates the momentum of the specified tracks from their Coulomb scattering."
    };

  fhicl::Atom<art::InputTag> tracks{
    fhicl::Name{"tracks"},
    fhicl::Comment{"tag of collection of tracks to be analysed"}
  };

}; // struct Config

The idea is that when Config is enclosed in a fhicl::Table and its description is requested, the content of the object(s) of type fhicl::Description is dumped as header of the parameter documentation.

[knoepfel]

Comment by @knoepfel on 2017-08-14 16:26:14

---

This is a sensible request. It is somewhat non-trivial, however, to come up with an implementation that interacts seamlessly with the current system.

[knoepfel]

Comment by @knoepfel on 2019-09-17 19:16:27

---

After discussing this issue with Andrei (added as watcher), who also would benefit from this facility, we believe the best approach is to separate the actual configuration, and the description of the module for which the configuration struct is implemented. Instead of:

struct Config {
  fhicl::Description desc{"This module does such-and-such."};
  ...
};

using Parameters = Table<Config>;

The code would instead look (heuristically) like:

struct Config {
  ...
};

struct Description {
  auto text() { return "This module does such-and-such."; }
};

using Parameters = Table<Config, Description>;

I will work to produce a design that reduces the amount of boilerplate needed for the Description type.