+1 for (a).
— *Joris Van Remoortere* Mesosphere On Tue, Oct 20, 2015 at 3:02 PM, Benjamin Mahler <benjamin.mah...@gmail.com> wrote: > +1 for (a), in this case the wide sweep only touches the license comments, > so it won't be disruptive to history. > > On Tue, Oct 20, 2015 at 11:59 AM, James Peach <jor...@gmail.com> wrote: > > > > > > On Oct 20, 2015, at 8:55 AM, Bernd Mathiske <be...@mesosphere.io> > wrote: > > > > > > All, is changing every source code file prohibitive or not? > > > > > >> On Oct 20, 2015, at 10:01 AM, Benjamin Bannier < > > benjamin.bann...@mesosphere.io> 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 > > > > +1 for (a); there's no value in showing license headers to doxygen or > > tooling workarounds > > > > >> 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 > > > > > > > >
