Documentation is in implementation, not header files

[mdboom]

SOFA is very unusual for a C project in that it includes its documentation in the .c implementation files, not in the .h header files. This is the opposite of standard procedure in C, where generally a system library may have the header files (which also serve as usage documentation) and compiled binaries, but the original .c files are not available.

• IDEs/editors that provide pop-up help about functions are unable to do so.
• Tools that want to generate wrappers and include the documentation, or use the extra information about in/out variables contained therein, can not do so without the full source.

At the end of the day, this is probably a minor point relative to the effort it would take to fix it, but its rather irksome.

[timj]

The SOFA headers inherit their style from the SLALIB C headers from 25 years ago or more. Rewriting the source headers to get them in a form understandable by an IDE seems like a lot of work (and I'm not even sure the C files are standardised enough for that). [I rewrote most of the SLALIB headers when I ported SLALIB to PAL but that was a manual one off task]

[jwoillez]

Why not copy the documentation from the *.c to erfa.h, as part of sofa_deriver.py in https://github.com/liberfa/erfa-fetch? Note: erfam.h, containing the types definition, is already well documented.

[rmathar]

I can provide a Doxygen file that produces http://www2.mpia-hd.mpg.de/~mathar/progs/sofa_api/ for example, if anyone is interested. These document the IAU SOFA libraryof May 2016 and would need to be updated.

[mhvk]

@rmathar - rather belated reply, but that looks wonderful! It would seem just the thing to generate a erfa.readthedocs.org or so.

[mhvk]

Looking at issues again as I'm trying to get the next erfa release out: @rmathar - I think the documentation you made is quite wonderful, and it would seem nice if we could have it be part of the project. Is it something that we could run on, e.g., readthedocs.org?

[rmathar]

The Doxygen source file is in https://www.mpia.de/~mathar/progs/sofa.dox , currently obsolete as the new version of the SOFA library of August 2020 is not yet worked into it.

The standard use in erfa would be to copy it into the github source code and run doxygen to generate either HTML or PDF files in the "make doc" section of the Makefile. [The better use of course would be to add this to the sofa releases themselves and to insert such computer-parseable documentation into each sofa-function.] That would keep the documentation at the place where it is used; putting such documentation to some other entirely detached storage system like readthedocs, where people will only find it with yet another login-manoevre does not make much sense IMHO.
R. J. Mathar

[mhvk]

Excellent! Do you have a programmatic way to generate this .dox file? If not, since we do very similar parsing to generate our python bindings, I think it should be possible to repurpose that machinery.

Note that I very much want to give the user the ability to look at the documentation themselves; the erfa.readthedocs.org would just be a standard place to be able to look up the rendered files (just like for our python bindings: https://pyerfa.readthedocs.io/en/latest/) - on the site, it would work by doing exactly what you suggest, doing some form of make docs (ideally generating the .dox file in the process).

p.s. And, yes, it should ideally go upstream; right now, they just typeset their ascii headers of all the functions.

[rmathar]

I hand-crafted the sofa.dox file by scanning at all the header files of the sofa distribution: inserting all the specific doxygen tags,
comparing the number and type of arguments etc. That file is meant to be interpreted by the doxygen.org scanner.

I am not aware of any means to auto-generate sofa.dox from the plain ASCII documentation. It's exactly this need of a lot of manual intervention that let me (an end-user of the SOFA library myself) publish this type of missing cross-linking information in my own web pages... if it were easy I'd not have done this...

[mhvk]

Fair enough... Though obviously we have done partially the same thing: to generate the python bindings with appropriate names and docstrings, propertly interpreting the error and warnings codes, etc., we already the documentation comments, in effect creating a python model of each function, as part of https://github.com/liberfa/pyerfa/blob/master/erfa_generator.py - I may have a look if we cannot repurpose that....

[mhvk]

I guess my point is that our auto-generated descriptions of the python functions are not that far off from what is needed to generate a description of the C function; for relatively complicated examples, see

• https://pyerfa.readthedocs.io/en/latest/api/erfa.apco13.html#erfa.apco13
• https://pyerfa.readthedocs.io/en/latest/api/erfa.ldn.html#erfa.ldn

[mhvk]

Hmm, but I see one things we're immediately missing is the nice one-sentence \brief items...