+1 for (a) non biding-though
> On 20 Oct 2015, at 10:01, Benjamin Bannier <[email protected]>
> wrote:
>
> Hi,
>
> I would like to ask for input on how we plan to fix (both short- and
> longterm) the interference of the license headers and Doxygen documentation
> (https://issues.apache.org/jira/browse/MESOS-3581).
>
> Currently, and in line with the respective guidelines, license blocks are
> wrapped in Javadoc-style comments which are also used for Doxygen
> documentation. This leads to Doxygen interpreting license headers as
> documentation for whatever entity follows them in the code, and heavily
> clutters the generated documentation (see e.g.
> http://mesos.apache.org/api/latest/c++/annotated.html). Given that
> considerable effort is done to improve the documentation this unfortunate.
>
> * * *
>
> For a TLDR; of the Jira issue, there are two ways to fix this:
>
> (a) change *all* license headers to be wrapped in e.g. `/* .. */`, also
> update the coding guidelines, or
> (b) perform some preprocessor-like magic in the Doxygen layer.
>
> Option (a) is very noise but obvious and stable; option (b) OTOH employs a
> simple but stupid text replacement under the covers codified in the Doxygen
> config; it might produce some artifacts and be surprising since the code
> Doxygen sees will be different from what is in the source.
>
> I personally believe option (a) is superior for purely technical reasons with
> option (b) a possible temporary workaround.
>
>
> To make sure that the generated documentation shows actual documentation
> content in overviews like
> http://mesos.apache.org/api/latest/c++/annotated.html and elsewhere we should
> fix this. Please comment in the Jira issue
> (https://issues.apache.org/jira/browse/MESOS-3581) your input on how you
> think this should be fixed (short- and longterm).
>
>
> Cheers,
>
> Benjamin
