+1 (and thanks for flagging this!) -- *Marco Massenzio* Distributed Systems Engineer http://codetrips.com
On Tue, Oct 20, 2015 at 12:14 PM, Joris Van Remoortere <[email protected]> wrote: > +1 for (a). > > > — > *Joris Van Remoortere* > Mesosphere > > On Tue, Oct 20, 2015 at 3:02 PM, Benjamin Mahler < > [email protected]> > 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 <[email protected]> wrote: > > > > > > > > > On Oct 20, 2015, at 8:55 AM, Bernd Mathiske <[email protected]> > > wrote: > > > > > > > > All, is changing every source code file prohibitive or not? > > > > > > > >> On Oct 20, 2015, at 10:01 AM, 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 > > > > > > +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 > > > > > > > > > > > > >
