gmane.comp.lang.r.roxygen

include tag

meik michalke — 2013-05-01T22:08:23

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

Re: Quo Vadis ROxygen?

Hadley Wickham — 2013-02-04T20:45:58

Hi Joh,

roxygen3 will eventually get merged back in to roxygen2 - I definitely
plan to continue maintaining it, but other projects have priority at
the moment.

If you're having problems with roxygen3, it's probably namespace
related - if you ping me and remind me, I can try and make a few
minutes to investigate.

If you want to pitch in, the roxygen3 design is fairly well developed
and reasonably clean.  You'll need a decent understanding of S4, and
there's a bit of an intro in the readme
(https://github.com/hadley/roxygen3)

Hadley

On Fri, Feb 1, 2013 at 1:10 PM, Johannes Graumann
<johannes_graumann-S0/GAf8tV78< at >public.gmane.org> wrote:

Quo Vadis ROxygen?

Johannes Graumann — 2013-02-01T19:10:28

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

Re: Templating mechanism?

Hadley Wickham — 2013-01-10T20:03:53

Hmmm, I'd prefer to just rely on the existing tools for checking Rd
files.  Otherwise you end up having the same requirements coded in two
different places.

Hadley

On Fri, Jan 4, 2013 at 1:17 AM, Johannes Graumann
<johannes_graumann-S0/GAf8tV78< at >public.gmane.org> wrote:

Re: Templating mechanism?

Johannes Graumann — 2013-01-04T07:17:24

Hello Hadley,

Exactly. Something like

In case the documented thing is a function we are 
absolutely expecting (absence throws error):
< at >examples
< at >details
...
recomending (absence issues warning):
< at >seealso 
...

In case the documented thing is a data set ...
etc.

Wouldn't that make sense?

Joh

On Thursday, January 03, 2013 17:30:23 Hadley Wickham wrote:

Re: Templating mechanism?

Hadley Wickham — 2013-01-03T14:30:23

Hi Johannes,

I'm not sure what the purpose would be do - do you want some automated
way of ensuring that you've provided a predefined set of tags?

Hadley

On Sat, Dec 29, 2012 at 11:40 PM, Johannes Graumann
<johannes_graumann-S0/GAf8tV78< at >public.gmane.org> wrote:

Templating mechanism?

Johannes Graumann — 2012-12-30T05:40:37

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

Re: Roxygen3 Failure with uninformative error

Hadley Wickham — 2012-11-19T20:27:29

Hi Johannes,

It's probably because I haven't written the correct NAMESPACE file :(
You might be able to work around it by cloning the repo and using
devtools::load_all to load it - that's my development process so it
should work.

Hadley

On Mon, Nov 12, 2012 at 11:54 AM, Johannes Graumann
<johannes_graumann-S0/GAf8tV78< at >public.gmane.org> wrote:

Re: Roxygen3 Failure with uninformative error

Hadley Wickham — 2012-11-19T20:27:29

Hi Johannes,

It's probably because I haven't written the correct NAMESPACE file :(
You might be able to work around it by cloning the repo and using
devtools::load_all to load it - that's my development process so it
should work.

Hadley

On Mon, Nov 12, 2012 at 11:54 AM, Johannes Graumann
<johannes_graumann-S0/GAf8tV78< at >public.gmane.org> wrote:

Re: roxygen3

Peter Danenberg — 2012-11-15T11:24:57

Quoth Hadley Wickham on Prickle-Prickle, the 27th of The Aftermath:

I've been thinking a little bit about this, and it would be nice if
the roclet (viz. roccer) model resembled roxygen1 in the sense that it
were based on function-composition.

I did a live-coding demo at LARUG where I showed the audience how to
create a custom roclet; and all the coding-by-convention stuff (e.g.
remembering to write roc_process and roc_output) was a little painful.

The original idea was to chain a series of roclets together that
optionally (and perhaps non-destructively) altered the parse-tree in
some specified order; possibly doing I/O.

This enabled the creation of e.g. translation roclets that would alter
the description associated with srcrefs for later processing; to
accomodate which in roxygen2, I had to do awful things like assigning
to the parent frame:

  https://github.com/klutometis/larug-roxygen/blob/master/translation-roclet.R

It was painfully laborious compared to the mapping/composition model.

Anyway, you

Roxygen3 Failure with uninformative error

Johannes Graumann — 2012-11-12T17:54:41

Hi,

Sent first from wrong address and accordingly quarantined ...

Can anyone give me a hint what might be wrong if Roxygen3 gives the following:

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

Re: Roxygen3 ready for review

Hadley Wickham — 2012-09-25T05:41:45

Yes, that's definitely on the to do list - but I'm waiting on support
from the RMarkdown package.

Hadley

Re: Roxygen3 ready for review

Carl Boettiger — 2012-09-24T23:43:41

Hi All,

Is there any chance Roxygen3 could support a bit of markdown syntax?

Being a literate programming technique, Roxygen syntax is clearly designed
to be easily readable in raw format.  As such, having to add \code\link,
\item and other approximately LaTeX syntax of the .Rd files feels wrong.
 I'd love to be able to add links or lists (explaining parameter arguments,
return objects) with the markdown-style syntax instead.  Do others think
this would be useful, or am I missing something?

Just a thought,

Carl

On Mon, Sep 17, 2012 at 10:08 AM, Hadley Wickham <h.wickham-Re5JQEeQqe8AvxtiuMwx3w< at >public.gmane.org>wrote:

Roxygen3 ready for review

Hadley Wickham — 2012-09-17T17:08:42

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

Re: Usage for S4 classes

Hadley Wickham — 2012-09-13T10:53:03

Ah ok, so slots should generally be considered private unless
documentation is explicitly requested for them.

Hadley

Re: Usage for S4 classes

Michael Lawrence — 2012-09-13T03:20:39

I'd personally prefer that if there is such functionality, it is disabled
by default, since we tend to like to hide new(). Since overriding
initialize is problematic, using new() would expose the slots, which are
normally considered implementation details. Others may differ.

Michael

On Wed, Sep 12, 2012 at 5:45 PM, Hadley Wickham <h.wickham-Re5JQEeQqe8AvxtiuMwx3w< at >public.gmane.org> wrote:

Re: Usage for S4 classes

Hadley Wickham — 2012-09-13T00:45:55

Or should that just come from documenting the constructor and class in
the same file?

Hadley

On Wed, Sep 12, 2012 at 7:44 PM, Hadley Wickham <h.wickham-Re5JQEeQqe8AvxtiuMwx3w< at >public.gmane.org> wrote:

Usage for S4 classes

Hadley Wickham — 2012-09-13T00:44:19

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

Re: Autodocumentation for S4 classes,methods and generics

Hadley Wickham — 2012-09-12T17:37:40

I think that should just work.  I have:

setClass("R5ClassObject", contains = "S4ClassObject")

so reference classes will inherit all S4 class behaviour by default.


As a first pass, the class documentation could just include a list of
all methods and their docstrings.

Hadley

Re: Autodocumentation for S4 classes,methods and generics

Michael Lawrence — 2012-09-12T17:29:52

Reference classes basically are S4 classes, so it would be nice to the same
basic features for both.  Reference classes of course have some additional
notions, like class-based methods and fields that are potentially
encapsulated via active bindings and thus suitable for public access. Not
sure how one would rectify roxygen with the docstring feature.

Hadley

Re: Autodocumentation for S4 classes,methods and generics

Hadley Wickham — 2012-09-12T17:21:11

Do you have any particularly good examples where this is useful?


S3 is already supported - although there's no formal notion of an S3
class so there's only so much we can do.

I'm not sure what supporting reference classes would entail (esp. with
the alternative doc system built into ref classes).  Do you have any
hand written Rd files you could share?

Hadley