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