wiki:CcbMeeting20120307
Last modified 7 years ago Last modified on 05/04/2012 07:34:56 AM

From: Technical Control Team

TCT Meeting 7 March 2012

Attendees

Robyn Allsman
Kian-Tat Lim
Serge Monkewitz
Robert Lupton
Russell Owen
Jim Bosch


Meeting Agenda

  • DM/Policy/NdArrayNamespaceChange, Jim Bosch
  • Avoiding TeX in Doxygen documentation, Robert Lupton
  • Phasing *.cc files out of Doxygen, Jim Bosch

Meeting Discussion

ndarray

In addition to the proposal, prior discussion on this topic by Russell (29 Feb 2012 14:08:54), GregoryDF (22 Feb 2012 20:56:21), and K-T (22 Feb 2012 21:22:11) is available from the [LSST-DATA] archives.

Jim reviewed his proposal. He added that the LSST version of ndarray would remain on our git-repo.

The proposal was unanimously accepted.

Avoiding TeX in Doxygen

Robert provided, prior to the meeting, the following:

Extracted from [http://dev.lsstcorp.org/trac/ticket/1894]

Use mathjax not latex to process LaTeX-like maths in doc strings

To generate docs from some packages (e.g. meas_astrom) we currently need to have LaTeX installed; 
this adds a new dependency to the system.

One option would be to remove all LaTeX-style markup from our doxygen strings, but:
    * Sometimes mathematics is very useful
    * Maths will inevitable creep back in, breaking the build 

An alternative is that doxygen supports mathjax to render mathematics written in "LaTeX" 
[http://www.mathjax.org]. This works by embedding javascript and calling an external renderer 
at read time not create time. It is also possible to provide a local copy of the mathjax renderer, 
but the result of a failure (e.g. on a plane) is merely to show the input LaTeX, which is usually 
quite acceptable.

So I propose that we enable mathjax. This requires changing "USE_MATHJAX" to YES in base/doc/base.inc

Doxygen interfaces with a math-jax service in order to render the latex formatting. There are web-based servers so that we could avoid installing the server locally if we wanted. Serge commented that it was easy to install the server locally.

Robert commented that if we don't have an external connection at the time of doxygenation, we will just get in-line 'raw latex'.

We could also default to latex if the user has that available in his path. We would also need a way for the user to intentionally disable math-jax use.

Decision No action has been taken on this. The service should be tested and the result evaluated.

Phasing *.cc files out of Doxygen

Jim Bosch provided the following email as this issue's proposal:

At the beginning of Winter2012, we changed the documentation standards to prefer Doxygen in headers over source files (I don't recall how strong that statement was on the "could/should/must" scale, and I couldn't find the answer on trac).

Anyhow, this has the potential to make our Doxygen builds much easier to maintain, at least in terms of reducing spurious warnings, if we stop running Doxygen on *.cc files whose documentation has been moved fully into headers. A lot of the warnings we're getting in afw come from Doxygen's inability to match member function declarations to their definitions when templates and/or namespace aliases are involved.

Eventually, we could do this on a per-package basis by editing doc/SConscript. Before then, I'd like to start putting / \cond or #ifndef DOXYGEN bits in specific source files.

However, our Doxygen is currently configured to pull implementation comments out of our source files as well, so we'd lose that. I'm okay with this; I'd actually prefer to see a clear boundary between interface documentation and implementation comments, and I think this would help enforce that. But there might be other philosophies out there, and I wanted to see what others thought before I started disabling Doxygen on any source files.

Any thoughts?

Initial comments from the group:

  • It is possible to disable the doxygen build of individual files in the doxygen builder.
  • It is possible to turn-off in-line doxygen parsing. However that would not solve the problem of the excessive warnings.

Jim pointed the group to the 'afw' .cc files which show how '/ \cond' and '/ \endcond' have been used to minimize warnings during doxygen generation but still allow doxygen processing of *.cc files. This method would allow a phased transition to complete removal of doxygen use within the *.cc files. See 'afw/src/math/ConvolveImage.cc as an example.

However, it was felt by most that doxygen processing of .cc files should stop immediately.

The TCT approved the proposal as-is except that the transition should be effected using the 'scons' exclusion of the *.cc files from doxygen processing.