Documenting your code

Along with any code submission to the LAL library, you will need to supply documentation. Keep in mind, the documentation, like the code, is a deliverable and it must be written to the standard outlined in the LAL-Spec. This chapter gives specific instructions on how to meet the standard.

Also keep in mind that, unlike most code projects that physicists work on, this code may still need to be maintained long after the author has been denied tenure and starts working for a dot-com company. This puts a heavy burden on the documentation: not only should it help you maintain your code, but it should require minimum effort for anyone to figure out how the code works and how to fix it. If you find yourself saying ``The easiest way for me to maintain my code is ...'', you have missed the point.

In this chapter we discuss a few preliminaries, and give a general outline of the documentation for a package. Chapter is an example of how a the documentation for a LAL package should be laid out. In Chapter we explain how to use the auto-documentation system (laldoc).