|
|
# Problem Statement
|
|
|
|
|
|
We want to avoid a situation where the code drift away from from the documentation. Since the code is evolving quickly, developers might (will) easily forget to go to the doc page when the configuration evolve.
|
|
|
|
|
|
To avoid that, we need a solution where that documentation can easily be added as close as possible as the property introduction.
|
|
|
|
|
|
# Solution
|
|
|
|
|
|
We use the [Proxy Pattern](https://en.wikipedia.org/wiki/Proxy_pattern) to offer a [std::ostream](http://www.cplusplus.com/reference/ostream/ostream/) like interface to the property documentation [^1].
|
|
|
|
|
|
That proxy will add to the property `<name1>....<name n>` the property `<name1>....<name n>.description` property containing the documentation.
|
|
|
|
|
|
# Examples
|
|
|
|
|
|
### Inside the `fargOCA::Parameters` class methods
|
|
|
|
|
|
This is the most common case at this point. The proxy object is returned by the `documentation` method:
|
|
|
|
|
|
```
|
|
|
documentation("Disk.Foo.Bar") << "This property is used blah blah blah.";
|
|
|
```
|
|
|
|
|
|
### Outside
|
|
|
|
|
|
The proxy can alway be directly instantiated:
|
|
|
```
|
|
|
PropertyDocProxy(cfg, std::cerr, "Disk.Foo.Bar")
|
|
|
<< "This Property bla blah...";
|
|
|
```
|
|
|
### Rendering
|
|
|
|
|
|
* The documentation appears in all generated config file (in particular, those converted on the fly from legacy parameter files).
|
|
|
* The `tools/cfg/convert_config` command print the documentation in mark down format. Such an output will be periodically be [uploaded to the web site](Property-Tree-Documentation).
|
|
|
|
|
|
|
|
|
[^1]: This stream like object provides all the formatting capabilities of a regular `std::ostream`. |
|
|
\ No newline at end of file |