[Roxygen-devel] Parsing roxgen blocks

[Hadley Wickham]

> Indeed, this is a slight complication which is  solved (is it?) by
> stacking the evaluation environments. That is, each new code chunk is
> evaluated in an environment whose parent is the environment from the
> previous evaluation.

Yes, I think that would work (although I'm not sure what will happen
with the S4 method tables)

> Hmm, indeed, I have been overoptimistic. But s3 methods are just
> functions, and automatic detection is not possible anyways.  The user
> have to declare them as S3 method anyways. So nothing is lost with
> respect tot he current implementation.

See https://github.com/hadley/roxygen3/blob/master/R/s3.r for my code
to determine is a function is an s3 generic or method.  I think it
should be pretty robust.

> Very simple one - just functions, no dispatch no objects. You will need
> something similar anyhow, as there are no objects at that stage, and no
> OO system can be used.

True.  I wavered back an forth on using environments vs. special named
functions.

>   > Why wouldn't should these functions just be single method classes
>   > that inherit from RoxyDetector or similar?

I was thinking more that instead of

roxy_env_inspector <- new.env(parent = emptyenv())
roxy_env_inspector[["S3"]] <- ...
roxy_env_inspector[["S4"]] <- ...

you'd do

setClass("RoxyInspector")
setClass("S4RoxyInspector", contains = c("RoxyInspector"))
setMethod("inspector", signature("S4RoxyInspector"), ...)
setClass("S3RoxyInspector", contains = c("RoxyInspector"))
setMethod("inspector", signature("S3RoxyInspector"), ...)

and then retrieve all the inspectors by using a S4 introspection
function to get all children of RoxyInspector.

> Whatever the textual representation by which object X is generated X <-
> new(..), or X <- X.constructor(), or createObjectX(), or X <- eval(...)
> will always have the same result.  It is much easier for the end user,
> who is not forced to use a specific declaration for roxygen to work. All
> what matters is the end object(s) which the code generate.

Ok, agreed.  If you can do it, I'll happy include the code :)

> I still find the object_from_call mechanism a bit tricky, it's not only
> the call name, but also the object name that plays the role. So the call
> parser should be very smart, not only about how to detect the call name,
> but also on how to detect the name of the object. Am I missing anything?
> Where does the 'name' in the last call comes from:

Ooops that's a bug - name is never used - it's always computed from
the call in the individual "methods".

But I think you need to have both the value of the object and it's
name - either alone is not enough to be able to fully document the
object.

> I have done this with ess-developer
> (http://ess.r-project.org/Manual/ess.html#ESS-developer) which allows
> seamless evaluation of the code directly into the package environment
> and namespace instead of the .GlobalEnv. So far so good, no problems at
> all.

Ok, cool!  We should probably share approaches - Winston contributed a
pretty complete namespace environment generator for devtools:
https://github.com/hadley/devtools/blob/master/R/namespace-env.r

> Unless I have missed something very basic, I am pretty optimistic about
> all this story:)

Great - I'm very happy to be proved wrong.

Hadley

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