[Roxygen-devel] roxygen3

[Hadley Wickham]

> It looks like you want a simple interface, but it ends up being a cross
> between S3 and internal roxygen object (i.e. tag) keeping system. Sort
> of _roxyClasses_ approach, and it looks like you haven't yet get to the
> inheritance and extension mechanism.

Hmmm, point taken.

> (Actually, I think I started understanding why you proposed to split the
> package and to keep tags separately. To simplify the extension of
> tags(that is it?). If the tags are S4 classes, then this is not a
> problem. Any package can extend the system!)

I'm more interested in establishing the boundaries between "this is a
useful system for writing a documentation domain specific language"
and "this is how Hadley thinks you should do documentation".

>   HW> I think this is more inline with how roxygen2 works. You can't have a
>   HW> methods that just work with a single documentation block + object
>   HW> (rocblock for short) at a time, because some tags work more globally
>   HW> (e.g. @family, @include, @inheritParams).  That's more of a comment on
>   HW> your suggested function names rather than using S4 - but it does have
>   HW> a big impact on the API.
>
> I didn't think about that. I barely understand how roxygen works as
> yet:). You have rockblock_parser class already. I guess it's just a
> question of S3 or S4 then.

I'd appreciate any comments on the overall design as described in my
other email.

> Actually, the parsing generic (roxyParse or whatever) can by default
> take two arguments, the object and the whole bunch of rocblocks. Each
> tag will decide for itself whether to use rockblocks argument or not.

I think you need some subclasses that work with a single tag or a
single roc, because you can cache them more efficiently.

> I guess you are already doing something similar, but I am a bit confused
> of why the distinction between parse_rocblocks and roccer$parser is
> necessary.

Me too ;)

>   HW> My feeling is that generally R users are more familiar and comfortable
>   HW> with S3 rather than S4.  So it might make it less likely to get
>   HW> contributions.
>
> Now roxy users have to learn roxyClasses system ;). And by building new
> packages on S3 you actually contributing to rooting and roting of
> S3. It's surprising why people are so stuck with it. S4 is so simple;
> there are only two main functions setClass, setMethod. Nobody needs to
> know more.

Well, you also need to know something about how methods are
dispatched, and you need to invest much more in up-front design.

> I can hardly add anything new to well known S4 advantages. Here are a
> couple of obvious thoughts:
>
>   - S4 is R standard and R-core encourages using it. S3 is virtually
>     subsumed to S4 right now.

I think that's overstating the case - some of R core like S4, and some
of them hate it. There are still plenty of R core members writing new
S3 classes, generics and methods.

But I accept your other points, and it would be good practice for me
to do a package in S4 style. I'll have a go at converting to S4 in the
next week or so.  I'll probably finish off the S4 documentation code
with the current system (so roxygen3 is basically feature complete)
and then I'll start the process of converting to S4.

>   HW> Ah, I see. And you see this being the role of roxygen to generate,
>   HW> rather than the editor?
>
> Right, but if one editor have already done that (ESS for example) why
> not to reuse the code in an editor independent way?
>
>   HW> It seems like there's a lot that people could disagree on (##' vs
>   HW> #', do you need @author) etc.
>
> It could be customized in options$roxygen or alike. If roxygen
> establishes an uniform customization interface, then editors will be
> forced to pick it up from there.

This isn't something I'm that interested in, but it would certainly be
easy for someone to submit a patch to implement it :)

Hadley

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