Mark.Bravington@csiro.au
2004-Sep-21 08:10 UTC
[Rd] checking for _non-existing_ -> documentation and sources at one place.
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@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@csiro.au
#
#
#
#Dipl. bio-chem. Witold Eryk Wolski @
#MPI-Moleculare Genetic
#Ihnestrasse 63-73 14195 Berlin 'v'
#tel: 0049-30-83875219 / \
#mail: witek96@users.sourceforge.net ---W-W----
http://www.molgen.mpg.de/~wolski
wolski@molgen.mpg.de
Possibly Parallel Threads
Wisdom of the Ancients
