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 <jos...@mesosphere.io> 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 <ma...@mesosphere.io>
> 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 <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
>>>>>>
>>>>>
>>>>>
>>>>
>>>
>>
signature.asc
Description: Message signed with OpenPGP using GPGMail
