documair

The development of this package was led by the idea that it is a bad practice to separate code and documentation. Code and documentation should be at the same place so that both can easily be modified simultaneously. We proceed according to this principle since the middle of the 90ties using a Perl script (a very convenient language for this kind of tasks). Now, we share it with the community by the more convenient way of an R package. The recent development of R make things quite easy.

To use documair, each code defining an object (either function or variable) must be encapsulated within a series of tagged comments; we propose tags but their values can be adapted as you wish (by modifying the ‘documair0$tag$v’ list). From these tagged comments, documair automatically writes ‘Rd’ files and gathers them with a few more files to produce the complete package until the ‘tar.gz’. For some specific objects, the user can write manually the ‘Rd’ file. All the necessary files must be gathered in a unique directory. In it, the user must place the following set of mandatory files (in the following ‘pkg’ will designate the name of the package) :

1. A ‘pkg.DESCRIPTION’ file: the standard text DESCRIPTION file to be associated to the pack-age. The NAMESPACE file is automatically created from the exported objects and the pres-ence of C and Fortran files.

2. A ‘pkg.package.Rd’ file: a text file describing in Rd syntax the general description of the package to appear in the documentation. This file can be slightly supplemented by documair to add some additional information.

3. As many as wanted ‘foo.code.r’ files where are placed the documented code of each object. Each files can include more than one object. The extension ‘code.r’ can be modified within the ‘pkg.which.txt’ file.