mesos-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Bernd Mathiske <be...@mesosphere.io>
Subject Re: RFC: license headers interfere with doxygen documentation (MESOS-3581)
Date Wed, 21 Oct 2015 08:56:36 GMT
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 <benjamin.bannier@mesosphere.io>
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 <joseph@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 <marco@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 <
>>> joris@mesosphere.io>
>>> wrote:
>>> 
>>>> +1 for (a).
>>>> 
>>>> 
>>>> —
>>>> *Joris Van Remoortere*
>>>> Mesosphere
>>>> 
>>>> On Tue, Oct 20, 2015 at 3:02 PM, Benjamin Mahler <
>>>> benjamin.mahler@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 <jorgar@gmail.com>
>>> wrote:
>>>>> 
>>>>>> 
>>>>>>> On Oct 20, 2015, at 8:55 AM, Bernd Mathiske <bernd@mesosphere.io>
>>>>> wrote:
>>>>>>> 
>>>>>>> All, is changing every source code file prohibitive or not?
>>>>>>> 
>>>>>>>> On Oct 20, 2015, at 10:01 AM, Benjamin Bannier <
>>>>>> benjamin.bannier@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
>>>>>>> 
>>>>>> 
>>>>>> 
>>>>> 
>>>> 
>>> 
> 


Mime
View raw message