Documentation

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:

1. A short description of the code's function and keywords must be written for each new module and library added to the PSI3 package.
   • Direct inclusion in the PSI3 manuals -- binaries (modules) should be included in the user's manual and libraries in the programmer's manual.
   • A UNIX man page -- These provide ``quick-and-dirty'' access to the program options even when logged in remotely via a terminal window. A man page should be added for each PSI3 module, and doing so is not difficult when working off another PSI3 man page as a template. To access the PSI3 man pages, you will need to add the man directory to your MANPATH. For example, if you run csh or tcsh, and assuming PSI3 has been installed in /usr/local/psi3-bin, the following can be added to your .cshrc or .tcshrc file:

     setenv MANPATH /usr/local/psi3-bin/doc/man:/usr/share/man
     

     The usual man path should be added after the PSI3 part and will be different for different systems. Different directories are separated by colons.
   • It is also helpful, particularly for complex programs or libraries, to have even more extensive documentation. Certain parts of PSI3 have been documented in more detail via HTML documents (e.g., cints, libdpd, and libpsio). These documents are stored in the associated source code directories and installed in the installation directory under doc/html.

2. 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 5.7.

Note also that full documentation should also include citations to any relevant publications upon which the code may be based.