[Roxygen-devel] Parsing roxgen blocks

[Hadley Wickham]

>   > 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:
>
> Precisely what I had in mind (I was convinced that roxygen is already
> doing that and didn't bother to explain).
>
> Each code chunk should be evaluated in a new environment. Then
> environment is inspected and all the new objects/classes/methods are
> returned.

So you have to evaluate everything twice? Or do you copy over the
results once you've done run it? (Is that even possible for S4?)
Otherwise, how do you make sure that the code actually runs?

i.e. how do you evaluate this code?

a <- 1
b <- 2
a + b

That approach also starts to get complicated with S4 because it's
picky about how you create the environment.

> There might be an environment (or list) in roxygen namespace holding all
> the object guessers (roxy_env_inspectors?). Each of them is called and
> should return a list of new objects detected.
>
> The basic one just looks for normally assigned objects,
> roxy_env_inspector.S3 looks for S3 tables *in* the evaluation
> environment, roxy_env_inspector.S4_classes looks in class table and gets
> the classes defined, roxy_env_inspector.S4_methods searches the S4
> table.

I just don't see the big advantage of this over parsing the call.
This approach will be much more expensive because now you have to run
multiple tests after every single expression.  (Also I'm pretty sure
your approach for S3 won't work, because those S3 tables are created
by namespace definitions, not by evaluating a function)

> If a package declares some wiredo side effect initialization (which is
> pretty rare) it should define roxy_env_inspector.Wierdo_thing and add it
> to roxy_env_inspectors environment (which should not be sealed in the
> package).

So now you are defining your own object system ;)  Why wouldn't should
these functions just be single method classes that inherit from
RoxyDetector or similar?

>   >> 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.
>
> Each call to meta functions setClass, setMethod etc creates a table *in*
> the evaluation env, if it is a top environment (environment should be
> explicitly designated as a top environment for this to work).

I have had many problems trying to do this right for devtools, so I'm
not so sure it's that simple.

>   > 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.
>
> Ok, I will wrap up a proof-of-the-concept code.

Looking forward to it!

Hadley

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