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
