[R] self documenting workspaces, and the proper role of the dot

[Thomas Lumley]

On Mon, 19 Feb 2001, John Aitchison wrote:

>
> again I ask for some suggestions : I don't mind being told to RTFM as long
> as I get a few hints as to where to look <g>
>
> suppose I want to document the set of functions and vectors that I have in
> a workspace, and I would like to make that workspace 'self documenting' ..
> so I could open up that particular workspace in a few months and know what
> xdiff contained ..etc. Essentially I want a listing of objects and their
> 'descriptions'.
>
> I could write a function to list each object and its 'description' easily
> enough, but names() does not quite fit the bill. For a 'scalar' I can use
> names(), but for a vector names() wants every element named - I guess I
> could just use the name of the first element but this is a bit kludgy. For
> a function I don't see any way of using names(), but I guess I could
> be disciplined about this and have every function that is specific to the
> workspace return some descriptive string.
>
> One possibility that occurred to me is to have some 'documentation'
> objects
>
> eg fred.doc<-"this is function fred and it does whatever"
>
> and write a function to list these (or the names of scalars) ..I suppose
> that is OK , if a little inelegant.
>
> So this is less of a technical question than a housekeeping/procedural one
> .. if someone has a nice solution or if there are some features of R that
> I have overlooked that could be of assistance, I would be very interested.


YOu could attach a "doc" attribute to everything. This has the
disadvantage that for objects with no special "print" method the attribute
would always be printed with the object.

attr(a,"doc")<-"A is for apple"

and you could write a function that listed objects and documentation using
something like
sapply(ls(),function(x) attr(x,"doc")



>
>
> thanks
>
> somewhat separate topic : the dot
>
> I'd also appreciate it if someone could clarify for me the proper role of
> the dot. It appears there are no semantic/syntactic restrictions on its
> use, as in
>
> > .fred<-1
> > .fred
> [1] 1
> > .fred.fred<-1
> > .fred.fred
> [1] 1
> > .fred.fred.fred.fred.fred<-1
> > .fred.fred.fred.fred.fred
> [1] 1
> > ...fred<-1
> > ...fred
> [1] 1
> > ...fred.............................fred<-1
> > ...fred.............................fred
> [1] 1
> > fred...fred.............................fred<-1
> > fred...fred.............................fred
> [1] 1
>
> or even ....<-1:10
>
> but I suspect there are some conventions at work, with which I am not
> au fait. For instance I have noted that in ls()  .prefixed objects can be
> ignored, by option.
>
> So is an initial dot intended to denote 'internal' (or 'working') in
> function names?
>
> What about  p.value ? is there some reason for this, as opposed to pvalue
> ?
>
> In the oo languages with which I am most familar, dot is used to denote
> hierarchy eg text.font.style  .. is there a similar intention at work
> here?


The dot is used in four different ways. It's almost always clear from
context which is intended.

1) Method separator
	print.default
	print.lm
	print.formula

are "print" methods for "default", "lm" and "formula"

2) Separating words: since the underscore can't be part of a variable name
we can separate words either by InternalCapitals
	NextMethod
	commandArgs
or by.dots
	data.frame
	lm.influence
	split.plot
	filled.contour
	p.value

3) As in Unix, we use a leading dot to hide global variables and functions
that people would be better off not knowing about.
	.packages
	.Options
	.Generic

4) The ellipsis ... is a special token used to represent extra function
arguments. These can be positionally matched by ..1, ..2

One of the complications in UseMethod/NextMethod is that dots can mean
more than one thing.  We need to know that as.data.frame.matrix is an
"as.data.frame" method for "matrix" arguments, but print.summary.lm.null
is a "print" method for "summary.lm.null" objects. If someone wrote a
function "as.data" with a method for objects of class "frame.matrix" we
would be in trouble, but it's no worse than what would happen if an
SAS ex-user wanted to write a function for the General Linear Model and
call it glm().


	-thomas

Thomas Lumley			Asst. Professor, Biostatistics
tlumley at u.washington.edu	University of Washington, Seattle

-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
r-help mailing list -- Read http://www.ci.tuwien.ac.at/~hornik/R/R-FAQ.html
Send "info", "help", or "[un]subscribe"
(in the "body", not the subject !)  To: r-help-request at stat.math.ethz.ch
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._