1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
|
Documentation is often the only link between code's author and code's
users. The usefulness of the code will depend heavily on the quality
of its documentation. One great failing of most of the PSI code is
that it contains little to no documentation. We strongly advocate
documentation of at least the first two types:
\begin{enumerate}
\item A short description of the code's function and keywords {\em must} be
written for each new module and library added to the \PSIthree\ package.
\begin{itemize}
\item Direct inclusion in the \PSIthree\ manuals --- binaries
(modules) should be included in the user's manual and libraries in the
programmer's manual.
\item A UNIX \file{man} page --- These provide ``quick-and-dirty'' access
to the program options even when logged in remotely via a terminal window.
A \file{man} page should be added for each \PSIthree\ module, and doing so
is not difficult when working off another \PSIthree\ \file{man} page as a
template. To access the
\PSIthree\ \file{man} pages, you will need to add the \file{man} directory
to your {\tt MANPATH}. For example, if you run csh or tcsh, and
assuming \PSIthree\ has been installed in \file{/usr/local/psi3-bin},
the following can be added to your \file{.cshrc} or \file{.tcshrc} file:
\begin{verbatim}
setenv MANPATH /usr/local/psi3-bin/doc/man:/usr/share/man
\end{verbatim}
The usual man path should be added after the \PSIthree\ part and
will be different for different systems. Different directories are
separated by colons.
\item It is also helpful, particularly for complex programs or libraries,
to have even more extensive documentation. Certain parts of \PSIthree\
have been documented in more detail via HTML documents (e.g., {\tt
cints}, {\tt libdpd}, and {\tt libpsio}). These documents are stored
in the associated source code directories and installed in the installation
directory under {\tt doc/html}.
\end{itemize}
\item Second, as mentioned before, the source code should be directly
documented by comment lines in the code. We use a special formatting
for in-code documentation, which is described in detail in section
\ref{code-commenting}.
\end{enumerate}
Note also that full documentation should also include citations to any
relevant publications upon which the code may be based.
|
