[Roxygen-devel] Parsing roxgen blocks

[Hadley Wickham]

[splitting out into separate emails instead of one huge one]

> Not that difficult,  S4 always leave traces in the evaluation
> environment, objects starting with:
>
>   methods:::.TableMetaPattern()
>   [1] "^[.]__T__"
>   methods:::.ClassMetaPattern()
>   [1] "^[.]__C__"
>
> Inspecting those, you know exactly what was installed.

Yeah, that's the easy part ;)  Now how do you find which comment block
they were associated with?

As far as I can see, there's no other way to do this apart from
parsing the call.  I also don't see another way to document user
created functions that modify the global state - e.g. add_roccer in
roxygen3 (this wouldn't be necessary if we used S4, but the principle
remains).

>   HW> Could you flesh out this example a bit more?  I don't understand why
>   HW> you'd want to document objects that aren't evaluated by the user.
>
> Ah sorry, that was stupid. I meant
>
>    eval({ a <- generate_object_a()
>           b <- generate_object_b()})
>
> Roxygen can make a convention if two declarations are followed
> imidiately after each over they souled be documented in the same
> roxy-doc and same Rd file:
>
> foo <- function(a) ..
> boo <- function(a) ..
>
> will put both foo and boo in the same file. Curently one needs two
> documentation blocks and rdname tag if I am not mistaken.

Again, the challenge is to connect the objects to the roxygen block.
Without parsing the call, how do you know that the comment block
should be attached to a and b?

One option would be to evaluate each source block as you encounter it.
That would resolve the problem above (and would make it possible to do
`my_class <- setClass` and still know that it was creating a class).
The problem is that the S4 functions don't seem to be very good at
returning what they're created:

> a <- setMethod("plot", "numeric", function(x, ...) {})
> str(a)
 chr "plot"

Which means you'd have to compare states of all the S4 class/method
tables before and after each call.  That seems slow and error prone to
me.

If you wanted to write some code to do it, I'd definitely be happy to
consider it, but given that my current system works, I'm not in a big
hurry to rewrite it.

Hadley

-- 
Assistant Professor
Department of Statistics / Rice University
http://had.co.nz/