Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Benjamin Bannier]

Hi,

thanks everyone for providing suggestions and feedback.

It seems we reached a consensus to implement option (a):

> (a) change *all* license headers to be wrapped in e.g. `/* .. */`, also 
> update the coding guidelines, or


and to keep improving the documentation in the code to provide more, helpful 
content.

We got 2 binding votes (+1 for (a)) from BenM and Joris, as well as 3 
non-binding votes from James, Marco, and myself, with no -1 for (a).

I will now propose a RR implementing the agreed solution.


Thanks again and cheers,

Benjamin 

Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Artem Harutyunyan]

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  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 
>>  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  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 
>>> 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 <
 jo...@mesosphere.io>
 wrote:

> +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 
 wrote:
>>
>>>
 On Oct 20, 2015, at 8:55 AM, Bernd Mathiske 
>> 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
>>> 

Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Bernd Mathiske]

Excellent idea! Let’s call this c)

It’s more work than a), but has to be done eventually anyway.

> On Oct 20, 2015, at 11:49 PM, Joseph Wu  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 
> 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 <
>> jo...@mesosphere.io>
>> wrote:
>> 
>>> +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 
>> wrote:
 
> 
>> On Oct 20, 2015, at 8:55 AM, Bernd Mathiske 
 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
>> 
> 
> 
 
>>> 
>> 



signature.asc
Description: Message signed with OpenPGP using GPGMail

Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Benjamin Bannier]

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  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 
> 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 <
>> jo...@mesosphere.io>
>> wrote:
>> 
>>> +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 
>> wrote:
 
> 
>> On Oct 20, 2015, at 8:55 AM, Bernd Mathiske 
 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
>> 
> 
> 
 
>>> 
>> 

Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Bernd Mathiske]

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 
>  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  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 
>> 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 <
>>> jo...@mesosphere.io>
>>> wrote:
>>> 
 +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 
>>> wrote:
> 
>> 
>>> On Oct 20, 2015, at 8:55 AM, Bernd Mathiske 
> 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
>>> 
>> 
>> 
> 
 
>>> 
> 



signature.asc
Description: Message signed with OpenPGP using GPGMail

RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Benjamin Bannier]

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

Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Benjamin Mahler]

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

>
> > On Oct 20, 2015, at 8:55 AM, Bernd Mathiske  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
> >
>
>

Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Joris Van Remoortere]

+1 for (a).


—
*Joris Van Remoortere*
Mesosphere

On Tue, Oct 20, 2015 at 3:02 PM, Benjamin Mahler 
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  wrote:
>
> >
> > > On Oct 20, 2015, at 8:55 AM, Bernd Mathiske 
> 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
> > >
> >
> >
>

Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[James Peach]

> On Oct 20, 2015, at 8:55 AM, Bernd Mathiske  wrote:
> 
> All, is changing every source code file prohibitive or not?
> 
>> On Oct 20, 2015, at 10:01 AM, Benjamin Bannier 
>>  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
> 

Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Bernd Mathiske]

All, is changing every source code file prohibitive or not?

> On Oct 20, 2015, at 10:01 AM, Benjamin Bannier 
>  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 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

Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Marco Massenzio]

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

> +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  wrote:
> >
> > >
> > > > On Oct 20, 2015, at 8:55 AM, Bernd Mathiske 
> > 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
> > > >
> > >
> > >
> >
>

Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)

[Joseph Wu]

+/- 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 
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 <
> jo...@mesosphere.io>
> wrote:
>
> > +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 
> wrote:
> > >
> > > >
> > > > > On Oct 20, 2015, at 8:55 AM, Bernd Mathiske 
> > > 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
> > > > >
> > > >
> > > >
> > >
> >
>