If this means that c) requires a), then we should do a) first, and then c) incrementally.
> On Oct 21, 2015, at 10:23 AM, Benjamin Bannier > <[email protected]> wrote: > > Hi Joseph, > > yes, doing the right thing and having everything documented would make most > of this cleaner. > > There is still an issue with e.g. namespaces (or anything else the particular > language allows to be extended later on): > > {foo.hpp} > /** Licensed .. > */ > > /** Foo is doxygenized! > */ > namespace foo {} > > {foo/bar.hpp} > /** Licensed .. > */ > > namespace foo { > /** Bar is doxygenized! > */ > struct Bar {}; > } > > Here the doxygen documentation for `foo` will contain both the license > header, and the namespace doc, so to prevent implicit inclusion of license > headers in the generated documentation one still needs to pick either of the > original options. > > > Cheers, > > Benjamin > > > >> On Oct 20, 2015, at 11:49 PM, Joseph Wu <[email protected]> wrote: >> >> +/- 0 (a) wouldn't hurt, but isn't the best solution. >> >> >> I'd vote for adding actual comment blocks to each class. Doxygen takes the >> comment block immediately preceding the class and uses that as the >> description. This means a file like this would show up correctly on >> Doxygen: >> >> /** >> * License ... >> */ >> >> #include <...> >> >> /** >> * Bar! <- This is what would show up on Doxygen. >> * A lot of our existing classes don't have a comment block >> * so Doxygen takes the License instead :( >> */ >> class Foo { >> ... >> } >> >> ~Joseph >> >> On Tue, Oct 20, 2015 at 2:32 PM, Marco Massenzio <[email protected]> >> wrote: >> >>> +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 >>>>>>> >>>>>> >>>>>> >>>>> >>>> >>> >
signature.asc
Description: Message signed with OpenPGP using GPGMail
