[Rd] checking for _non-existing_ -> documentation and sources at one place.

[Mark.Bravington at csiro.au]

Wolski wrote:

#>>>Has anyone a tool which is able to generate from 
#>>>#appropriately commented R-code files (e.g. <<example>>= 
#>>>#-example section) Rd files:

Mark Bravington mentioned something similar in the 'mvbutils' package:

Wolski wrote:

#
#
#Hi!
#
#Is it working with S4?

Mark's reply:

Don't know whether it works with S4 methods-- they're something I'm strongly hoping to avoid ;) However, I guess they have to start life as functions, and then get "methodized" via 'setClass' or whatever. Presumably my system would work on the original functions.

#  If I understand it right you have to keep each function in an separate file?

I don't actually keep function source code in files-- I rely on .Rdata files and the 'source' attribute of functions. My system also sets up another 'doc' attribute which contains the documentation. When the function is being sent to / read from a text editor (I have a function 'fixr' for that, but people could write their own), the 'doc' and 'source' attributes are combined into the one file so that you edit both together. Files only get used (i) for linking with a text editor, and (ii) as part of the automatic text backup system that's built-in to my utilities (I put quotes around "file" in my original post to avoid having to explain all this...)

For example, if I type 'library( debug); fixr( get.retval)' then in the text editor I see this:

structure( function() do.in.envir( envir=sys.frame( find.active.control.frame()), 
 j
)
,doc=flatdoc( EOF="<<end of doc>>"))
get.retval      package:debug

Show current return value when debugging

DESCRIPTION

When debugging a function, 'get.retval' gives the current return value, i.e. the result of the most recent valid statement executed in the function body, whether typed or in the original code, and excluding calls to 'go' etc.. Presumably only relevant when in exit code.


USAGE

get.retval()

...and the rest of the documentation...
<<end of doc>>

#Has nobody a perl-script that parseres the R files to generate 
#Rd files? Would someone be interested in something similar. If 
#so let me know please.

My 'doc2Rd' function pretty much does that, provided you follow simple rules when writing the "informal" documentation. It works directly from the 'doc' attribute though.

Obviously I have tweaked the 'mvbutils' to match the way I work, and so it might not suit everybody; but now that I've gone through the pain barrier of actually writing the stuff, I do find it makes package preparation and maintenance vastly easy.

Hope this helps

Mark



#
#What I am looking for is something what would resembles more 
#something like this:
#
#
#setClass("test",                                   #The test 
#data storage class.                               <-from this 
#the title section is generated automatically. 
#	representation(
#	size="numeric"                     # list size          
#                           <-section slots is generated automatically.
#	bla="list"                              # stores 
#content                            <-goes to section slots
#	##description : Stores test results....                 
#                                              <- goes to the 
#description section.
#	##example: x <- 
#new("test",size=1000,bla=vector("list",1000))                  
#          <-goes to the example section of the Rd file.
#	))
#
#setMethod("unlist" # unlists a list.
#	,signature(x="test"  #+                  <-the #+ sign 
#indicates that the docu of this function should be integrated 
#in the docu file of the class "test" above. If non in a speparate file.
#	
#	)
#	def=function(x,...)
#	{
#		.....	
#	}
#	#example: unlist(x)                       <- because as 
#indicated by the "+" above it is appendended to the example 
#section of the test-Class.Rd file.
#	)
#
#setMethod("unlist" # unlists a list.
#	,signature(x="test"                 # an object of 
#class test        <- no plus means it goes to a own 
#unlist-methods.Rd file and the comment goes to the argument section.
#               )                     
#	def=function(x,...)
#	{
#	##Description : function does this and that.
#	## further description...
#		....
#	}
#
#	##example : data(x)
#	## unlist(x)                      
#	)
#
#
#And then to have a tool eg something working like R CMD makeRd 
#(perl script)... which genreates Rd files out of it..
#Has nobody a perl-script that parseres the R files to generate 
#Rd files? Would someone be interested in something similar. If 
#so let me know please.
#
#
#/E
#
#
#
#*********** REPLY SEPARATOR  ***********
#
#On 9/17/2004 at 9:07 AM Mark.Bravington at csiro.au wrote:
#
#>>>Wolski wrote:
#>>> 
#>>>#I knew about prompt and promptMethods promptClass. They are 
#>>>#extremely useful if you are starting to write a package. But 
#>>>#what with existing packages that have to be rewritten?
#>>>#
#>>>#Having code and documentation in one place would be a great 
#>>>#help. Has anyone a tool which is able to generate from 
#>>>#appropriately commented R-code files (e.g. <<example>>= 
#>>>#-example section) Rd files:
#>>>#e.g. a noweb lit-prog file or patched version of Doxygen?
#>>>#
#>>>
#>>>Yes, there is such a tool-- or something close to it, anyway. My
#>>>'mvbutils' package lets you keep documentation in the same 
#source "file"
#>>>as the the function definition, appended at the end. 
#Usually, when I am
#>>>developing a function I start by writing informal 
#documentation (which
#>>>still displays with "?" but isn't an Rd file). Eventually I 
#convert the
#>>>documentation into a plain-text format close to the pager 
#representation
#>>>of R help files; this format can be converted into a .Rd 
#file using my
#>>>'doc2Rd' function. Once I am close to having a whole 
#package ready, I
#>>>use the 'formalize.package' function to set up the a whole 
#package; it
#>>>creates the skeleton and the .R source file, and all the 
#.Rd files via
#>>>'doc2Rd', ready for RCMD.
#>>>
#>>>For more details, have a look at README.mvbutils()
#>>>
#>>>Hope this helps
#>>>
#>>>Mark
#>>>
#>>>*******************************
#>>>
#>>>Mark Bravington
#>>>CSIRO (CMIS)
#>>>PO Box 1538
#>>>Castray Esplanade
#>>>Hobart
#>>>TAS 7001
#>>>
#>>>phone (61) 3 6232 5118
#>>>fax (61) 3 6232 5012
#>>>Mark.Bravington at csiro.au
#
#
#
#Dipl. bio-chem. Witold Eryk Wolski             @         
#MPI-Moleculare Genetic   
#Ihnestrasse 63-73 14195 Berlin                'v'    
#tel: 0049-30-83875219                        /   \       
#mail: witek96 at users.sourceforge.net        ---W-W----    
http://www.molgen.mpg.de/~wolski 
      wolski at molgen.mpg.de