include tag

hi,

after upgrading to R 3.0.0 and re-installing roxygen2 2.2.2, roxygenize() 
suddenly fails me with error messages about undefined classes (S4).

the classes however should be available, as the files setting them are 
included using the  <at> include tag. well, and it just worked flawlessly until the 
R upgrade. did R 3.0.0 break something in roxygen2?

viele grüße :: m.eik

-- 
dipl. psych. meik michalke
institut f"ur experimentelle psychologie
abt. f"ur diagnostik und differentielle psychologie
heinrich-heine-universit"at d-40204 d"usseldorf

hi,

after upgrading to R 3.0.0 and re-installing roxygen2 2.2.2, roxygenize() 
suddenly fails me with error messages about undefined classes (S4).

the classes however should be available, as the files setting them are 
included using the  <at> include tag. well, and it just worked flawlessly until the 
R upgrade. did R 3.0.0 break something in roxygen2?

viele grüße :: m.eik

--

-- 
dipl. psych. meik michalke

Quo Vadis ROxygen?

Hi,

I've been using roxygen2 for a while for documenting my amateurish 
enterprises and it has served me well.

I have, however, expanded the arsenal recently into using S4 classes and 
this is where documentation using roxygen stops lending the helping hand it 
used to and using it becomes an excruciating "how do I have to convince 
roxygen to build documentation for my code" ball and chains ...

I have been surfing around for alternatives, couldn't get the (old) s4 
branch in github, roxygen3 doesn't seem a smooth ride either - I'm at a 
loss.

Where do I go from here? Are there alternatives to roxygen? Is there a 
timeline for expanding toxygen(2)'s functionality into S$ space in a non-
beta(alpha) manner? Where can novices pitch in? What is to grow into a 
future proof version (crystal ball, where art thou?) - roxygen3?

I'd appreciate any input.

Sincerely, Joh

Hi,

I've been using roxygen2 for a while for documenting my amateurish 
enterprises and it has served me well.

I have, however, expanded the arsenal recently into using S4 classes and 

Templating mechanism?

Hello,

Is there a ROxygen-integral mechanism for doc-type specific templating? What 
I am looking for is a way in which I can define what ROxygen tags are 
expected/required in a function, a class, a data set. If documentation 
wouldn't comply to thosre rools there would be a warning at "document()"-
time ...

Thanks for your consideration.

Sincerely, Joh

Roxygen3 Failure with uninformative error

Hi,

Sent first from wrong address and accordingly quarantined ...

Can anyone give me a hint what might be wrong if Roxygen3 gives the following:
> roxygenise('.')
> Loading RCFPD # the package I'm working on
> Error in get(as.character(FUN), mode = "function", envir = envir) : 
>  object 'process_family' of mode 'function' was not found

Thanks for any insight.

I am playing with this because I am hoping to be able to document Reference 
Classes with it - is that feasible with roxigen3?

Thanks, Joh

Hi,

Sent first from wrong address and accordingly quarantined ...

Can anyone give me a hint what might be wrong if Roxygen3 gives the following:
> roxygenise('.')
> Loading RCFPD # the package I'm working on
> Error in get(as.character(FUN), mode = "function", envir = envir) : 
>  object 'process_family' of mode 'function' was not found

Thanks for any insight.

Roxygen3 ready for review

Hi all,

Roxygen3 (which will eventually get merged back into roxygen2) is at a
state where your comments on the design and implementation would be
appreciated. The code is at https://github.com/hadley/roxygen3/, and
there's a brief introduction to the structure in the readme.

The code is fairly complete - the code gives the same output as
roxygen2 (except for whitespace and that I haven't implemented
templates yet) on devtools, plyr and ggplot2.  It's about 50% slower
than roxygen2.

Hadley

--

-- 
RStudio / Rice University
http://had.co.nz/

Usage for S4 classes

Hi all,

Do you think it makes sense to add usage statement to S4 classes? i.e.

new("MyClass", a, b, c, d = 1)

where a, b, c, d are taken from the representation and prototype.

Hadley

--

-- 
RStudio / Rice University
http://had.co.nz/

Documenting S4 methods

Hi all,

After a survey of packages that use S4 and talking to a few people who
use S4 a lot, here are my thoughts on how method documentation would
work.

Methods need to be documented in three places:

* individually, for complex methods
* in the class (briefly)
* in the generic (briefly)

This distinction arises in part because there seem to be two main classes of
generic functions:

* Generics with many simple methods, like `length` and many of the methods in
  the `Matrix package`. There is little use of `...`. They often dispatch on
  multiple arguments. Typically, the individual methods don't need much
  documentation (i.e. it's usually obvious what `length` does)

* Generics with few complex methods, like `predict`, `anova`. These
  methods often use ..., to pass in additional information needed for a
  specific method. The individual methods need substantial documentation to
  (e.g.) explain the details of statistical operation.

So some methods need to document their parameters and provide
examples, others need a sentence or two, and quite a few no
documentation at all (like methods for `show`).

To deal with this variation, I propose that all documentation be

Autodocumentation for S4 classes, methods and generics

Hi all,

I'm starting to think more about S4 documentation, and wondered what
people thought about automatically adding:

* a list of all subclasses and superclasses to class documentation
* a picture showing the class graph to the class documentation
* a list of all methods to the generic documentation
* a list of all methods to the class documentation
* a list of "nearby" methods to method documentation

Should these be things that you have to turn on or turn off?

Hadley

--

-- 
RStudio / Rice University
http://had.co.nz/

Re: Parsing roxgen blocks

  >> Hadley Wickham <hadley@...>
  >> on Wed, 29 Aug 2012 12:16:15 -0500 wrote:

  > 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.

:D

I see. Use S4 for a storage. Well, a bit to fancy for me ;).

As an alternative you can just provide a function
roxy_register_detector(fun) which would just store fun in an environment
in roxy namespace. Simple, and everyone understands what happens.

  >> Whatever the textual representation by which object X is generated X <-
  >> new(..), or X <- X.constructor(), or createObjectX(), or X <- eval(...)

S4 implementation of <at> usage

Hi Vitalie,

It would also be really useful if you could sketch out the S4 design
to work with a tag like usage.

Would you need multiple dispatch so that usage looks like:

setMethod("ProcessTag", signature(tag = "RoccerUsage", object =
"function"), ...)
setMethod("ProcessTag", signature(tag = "RoccerUsage", object =
"classRepresentation"), ...)
setMethod("ProcessTag", signature(tag = "RoccerUsage", object =
"MethodDefinition"), ...)

Is that better than this? (effectively the same as the current s3
implementation)

setMethod("ProccessTag", signature(tag = "RoccerUsage"), function(tag, obj) {
  makeUsageObject(obj <at> value, obj <at> name)
}
setMethod("makeUsageObject", signature(object = "function"), ...)
setMethod("makeUsageObject", signature(object = "classRepresentation"), ...)
setMethod("makeUsageObject", signature(object = "MethodDefinition"), ...)

Currently the roccer implements the strategy design pattern so that
you can separately specify the parser and the output. How would you do
the same with S4?  Multiple inheritance?

setClass("RoccerUsage", contains = c("RoccerParseSingle", "RoccerOutRd"))
setMethod("ProcessTag", signature(tag = "RoccerUsage"), function(tag, roc) ...)

Design of roxygen3

Below I've attempted to outline the basic object structure of
roxygen3.  I would really appreciate any feedback.  There's a prettier
version at https://gist.github.com/3512194.  Thanks!

Hadley

[Important terminology: __roc__ is short for roxygen comment block,
__rocblock__ and for combination of roc and object that's being
documented]

# Roxygen design

The __roccer__ is the object in charge of processing a tag. It is made
up of two components:

* A `parser`, which is in charge of converting the raw text string
into an intermediate object that can be used by other roccers and is
turned into output

* An `rocout` object, which takes the intermediate format (after it's
potentially been modified by other roccers) and turns it into an
output format

Each of these is described in turn below.

Each roccer has a name, and a set of dependencies (currently stored in
`base_prereqs`.  Before the roccers are called, a topological sort is
performed to ensure that they are run in the correct order. This makes
sure (e.g.) that ` <at> title` is processed before the intro paragraphs,
and that ` <at> param` is processed before ` <at> inheritParams`.