3 Goals and Assumptions

 

The manpower in the PSAS project is not sufficient to provide multiple independent documentation versions of the code. Nor is such documentation suitable: PSAS will not have the degree of reuse which warrants the documentation to the extent of LAPACK.

On the other hand, we seek a way to maintain consistent in-code documentation of routine interfaces and produce a usable reference manual. Clearly the limitations in manpower require that we avoid documentation overlap, and choose a minimalistic approach. Thus we require in-code documentation that can be reused for LaTeX and HTML documents.

We define the goals of the code documentation as follows:

1. Documented code should be written in a text form, i.e., easily producible and readable by developers.
2. The documented code should be directly compilable, i.e., the documentation should be entirely contained as code comments.
3. Produce documentation in LaTeX and HTML format automatically, or at least with a minimum of user intervention.
4. Ensure good software engineering practices, e.g., avoid the possibility that changes in the code form an inconsistency in the documentation.

Special considerations apply at the DAO which make it necessary to search a specially tailored solution.

• The extensive use of LaTeXNot only is it imperative to generate LaTeX documentation, but it can be assumed that all code developers can write LaTeX without problems. In addition, all developers can understand LaTeX as normal text, thus in-code LaTeX source is sufficient for working without the finished documentation.
• There are usually several, but not numerous, members in any given software development project. Thus an industrial software development solution is not necessary or cost-effective.
• Since the DAO belongs to the research community, it is desirable to look for products in the public domain, in order to avoid large expenditures. Moreover EOSDIS requirements specify that DAO code will subsequently go into the public domain, therefore it would not be convenient to require users to install a proprietary documentation tool in order to use the code.