RFC: Deduplicate option descriptions?

[haasn]

I'm working on writing a dedicated documentation page (in markdown, converted to HTML by mkdocs) for all of the pl_options settings and their possible values. This just ended up being a duplication of all of the text we have in the comments attached to those fields in libplacebo/*.h, though.

I am very worried about the extra maintenance overhead of having options documented in two different places like this, so I am thinking about how to handle this best.

[haasn]

Put documentation inside src/options.c, generate markdown page from it at build time (and e.g. query the default values)

One problem with this approach is that we deploy docs via github pages, which does not currently have CI to actually compile libplacebo, but that would be a requirement to auto-generate the markdown from the options list

[haasn]

@jdek suggested we could just grep through all source files for stuff starting with triple slashes (///) and generate the markdown from that, e.g.

    /// ### `scene_threshold_low=<0.0..100.0>`, `scene_threshold_high=<0.0..100.0>`
    /// In order to avoid reacting sluggishly on scene changes as a result of
    /// the low-pass filter, we disable it when the difference between the
    /// current frame brightness and the average frame brightness exceeds a
    /// given threshold difference. But rather than a single hard cutoff, which
    /// would lead to weird discontinuities on fades, we gradually disable it
    /// over a small window of brightness ranges. These parameters control the
    /// lower and upper bounds of this window, in units of 1% PQ.
    ///
    /// Setting either one of these to 0.0 disables this logic.  Defaults to `1.0`
    /// and `3.0`, respectively.
    float scene_threshold_low;
    float scene_threshold_high;

[haasn]

For the current release, I decided to just duplicate the options in both places. Then we can think about how to better handle this.