[inlinedocs] new inline example ideas

[Keith Ponting]

> -----Original Message-----
> From: inlinedocs-support-bounces at lists.r-forge.r-project.org
> [mailto:inlinedocs-support-bounces at lists.r-forge.r-project.org] On
> Behalf Of Toby Dylan Hocking
> Sent: 23 April 2010 14:22
> To: inlinedocs-support at r-forge.wu-wien.ac.at
> Subject: Re: [inlinedocs] new inline example ideas
> 
> ok, you bring up some interesting points.
> 
> 1) I suppose it would be possible to have tests and examples that are
> different for the same function, so it would be nice to have the
option
> to do examples inline right after the function definition, and a tests
> separately in tests/fun.R. Then we could say
> package.skeleton.dx(tests="write") to write test files if they don't
> exist, and package.skeleton.dx(tests="overwrite") to overwrite
existing
> test files. And default of tests="dontwrite"

[KMP:] That sounds good to me. If both exist, which go in the docs and
which comes first in the docs? - the one from the function definition as
being likely to be simpler?

> 
> 2) I don't think there should be any problem with library() calls in
> example code. Already I add a suggests: line in my DESCRIPTION for
> packages I use in examples. You don't? I don't think it hurts anything
> to add a package to Suggests.

[KMP:] (I had forgotten suggests :-( Thus far my collection of packages
is sufficiently tree-like that everything needed has been in depends.)
The more general thought was thinking aloud as to whether anything legal
in an example would trigger warnings from the R function check, but I
suppose if that becomes a problem the answer is to use separate
example/test files as at present.

> 
> 3) I don't think in memory images of example code is a problem.
> 
> 4) Yes of course we will have to rework the parser for the ### return
> value, but this will not be too difficult. We can just look for a ###
> line after the return() line.

[KMP:] And in this case the Emacs left margin indentation of that line
makes quite a nice punctuation to emphasise the break from real function
to example.

> 
> 5) To keep the syntax simple I prefer to not have to explicitly start
> the example with ##example<<, but you do bring up a valid point about
> dontrun and dontshow, both of which I don't use very often. But I
think
> the whole point of inlinedocs is that everything should be simple and
> transparent, so it WILL be run and it WILL be shown. I feel OK not
> supporting dontrun and dontshow. Do you use these often? Will it be a
> problem?

[KMP:] I have never (yet) used dontrun or dontshow, but have come close
on occasion - maybe leave those out on a first implementation and wait
until if/when someone wants them? 

Keith

Keith Ponting
Aurix Ltd, Malvern WR14 3SZ  UK