On 10/9/2006 10:06 AM, hadley wickham wrote: >> Current .Rd documentation has some obvious problems: >> >> - the parser strips comments out of examples when it runs them >> - there's no way to put images into the documentation >> - the keywords aren't much use >> - there's isn't a definition anywhere of what the format really is, so >> it's hard to know >> whether something will work other than by trying it -- and it may break >> with the next release. >> - there's no way to link from a help man page to a vignette or other >> form of documentation. > > The main thing I don't like about the current system is the amount of > duplication - you have to supply a lot of information in the > documentation that is also encoded in the function (ie. everything in > the codoc check). This makes it unnecessarily painful when updating > documentation to reflect minor changes. The large distance between > code and documentation also makes it easy to forget to update the > documentation when changing the code. These are things that are > helped by inline documentation (which I am using)
Inline documentation isn't the only way to achieve what you want: better editing tools would help too. I don't know if ESS helps with this, but I could imagine a smart editor would be able to help with the updates in each direction. The big problem with this solution is that there is such a variety of editors in use, and most people are convinced that everyone else has made a big mistake in choosing theirs. However, there was talk in the summer about adding more keywords to .Rd files, to expand in various ways. A keyword that expanded to the arg list of a function might be a nice way to avoid duplication. If we had a way to put argument descriptions into the R file it could do a better job, but it would be tricky: e.g. what if the "file" arg in two objects to be documented in the same .Rd had different descriptions? I agree with Richard that we don't want to force separate man pages for every documented object. Duncan Murdoch ______________________________________________ [email protected] mailing list https://stat.ethz.ch/mailman/listinfo/r-help PLEASE do read the posting guide http://www.R-project.org/posting-guide.html and provide commented, minimal, self-contained, reproducible code.
