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

[John Aitchison]

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.


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?



John Aitchison
-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-.-
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
_._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._._