Re: [R] Block comments in R?

From: Richard A. O'Keefe <ok_at_cs.otago.ac.nz>
Date: Sun 08 Oct 2006 - 22:19:24 GMT


I wrote:

    R documentation comments really belong     in [.Rd] files where help() can find them.

Barry Rowlingson <B.Rowlingson@lancaster.ac.uk> replied:

	R documentation comments belong in .Rd files at the moment, but how 
	joyous would it be if they could be included in the .R files?
	

How joyous? About as joyous as a root canal job without anaesthetic.

I used to be a fan of including thorough documentation in code. Then JavaDoc hit the world, and many of the languages I use are following suit with their own EDoc or PlDoc or whateverDoc mess.

I have read far more Java than I ever wanted to, and the more Java I read the more I *hate* JavaDoc, and the more I am convinced that if you want to mix documentation and code you need *really* sophisticated tools (like Web in its various incarnations) or really simple tools (like Haskell's "Bird Tracks", a notation I have adapted to my own use for several other languages).

.Rd files are semisophisticated; if JavaDoc is a reliable guide, then shoving that stuff into .R files would be horrible.

Do I need to point out the single biggest difference between JavaDoc and .Rd? Maybe I do. .Rd files are *USEFUL*. (Because of references, examples, consistency checking, &c, and because they can describe closely related GROUPS of functions rather than being nailed to specific methods. The right documentation about the right topics at the right level of detail.) JavaDoc-style documentation seems to systematically encourage bulky documentation of low utility.

	  Okay, this is all part of my incessant whining to make R more like 
	Python, but I've found managing separate .Rd and .R files a pain. If .R 
	files could have embedded documentation you'd have one source for code, 
	documentation, tests etc. I did play about with this in the Splus days, 
	attaching documentation strings to functions with attributes, but it was 
	just kludgy without a proper mechanism.
	

Let me point out that right now there is NOTHING stopping anyone mixing .Rd and .R and test cases as they wish. How? Here's how:

	$poomat.1

.TH POOMAT 1 "Oct 2006" "Version 1.0" "USER COMMANDS"
.SH NAME
poomat - poor man's Tangle
.SH SYNOPSIS
.B poomat
file ...
.SH DESCRIPTION
.B poomat
extracts several interleaved files (such as documentation, source code, and test cases) from a single file. You can pack several files together using shell archives, tar files, or ZIP files, but those are distribution formats, not meant to be edited as single files.
.B poomat
lets you scatter a file in pieces, interleaved with other pieces, so that a function, the documentation for the function, and the test cases for the function can all be in one place.
.SH OPTIONS
None.
.B poomat
concatenates its input files just like
.IR cat (1)
or
.IR awk (1)
and writes to files named in the input.
.SH INPUT LANGUAGE
The input to
.B poomat
is a sequence of chunks. Each chunk is introduced by a line consisting of a dollar sign in column 1, immediately followed by a file name. The first chunk for any file name creates a new file; remaining chunks for the same file are appended to it.
.SH BUGS
Unlike
.IR tangle (1),
.IR ctangle (1),
and other Literate Programming tools, there is no facility for re-ordering chunks. Nor is there any macro facility.
.PP
It is up to you to make sure that the file names are portable. Stick to 8.3 file names without any directory affixes and you should be right. $INSTALL Edit the first line of the poomat file to refer to the right version of awk (nawk, gawk, mawk) for your system, and then move the poomat file to some directory in your $PATH. $poomat #!/usr/ucb/nawk -f BEGIN { output = "/dev/stdout" } /^[$]/ { output = substr($0, 2); next } { print >output }

Yes, I do mean the whole thing is a three-line AWK script. Yes, I do mean it is language-independent, and doesn't NEED to be built into R or anything else.
Yes, I do mean that the source code, documentation, and test cases get separated as part of the build process. So?

For people interested in doing stuff like that with C or C++, it really doesn't take a lot of work to make poomat notice a /[.][chCH][pxPX+]?[pxPX+]?$/ suffix and emit a #line directive. OK, here it is:

	/^[$]/ {
	    output = substr($0, 2)
	    if (/[.][chCH][pxPX+]?[pxPX+]?$/)
		print "#line", FNR+1, "\"" FILENAME "\"" >output
	    next
	}

So your C or C++ debugger can refer back to the original file. Maybe that should be in the official version, but R doesn't need it.



R-help@stat.math.ethz.ch 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. Received on Mon Oct 09 08:24:16 2006

Archive maintained by Robert King, hosted by the discipline of statistics at the University of Newcastle, Australia.
Archive generated by hypermail 2.1.8, at Sun 08 Oct 2006 - 23:30:09 GMT.

Mailing list information is available at https://stat.ethz.ch/mailman/listinfo/r-help. Please read the posting guide before posting to the list.