1. TCT Meeting 7 March 2012

## TCT Meeting 7 March 2012

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?