Please be aware that doxygen renders html differently than the middleman (templating engine that we use on mesos.apache.org). So before pushing changes please verify everything locally (https://github.com/apache/mesos/tree/master/support/site-docker.
Cheers, Artem. On Wed, Oct 21, 2015 at 1:56 AM, Bernd Mathiske <[email protected]> wrote: > 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 >>>>>>>> >>>>>>> >>>>>>> >>>>>> >>>>> >>>> >> >
