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