+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 > > > >
