[inlinedocs] new inline example ideas

[Thomas Wutzler]

Hello Toby and Keith,

interesting idea.
However, I think that such code would be confusing for people reading it
and do not know about inlinedocs. Also larger examples might clutter the
code and complicate inspecting a function from within a session (e.g.
body(apply)).

In addition, there will be potential problems with tools that check code
coverage of tests (RUnit has some attempts to do so).

I prefer to put small examples in comments and in addition to have
another mechanism to attach larger examples from uncommented source code
residing somewhere else. For the latter I would like to link it
explicitly (visibly documented) in an inlinedocs comment inside a
function of the sort similar to
##examplesInclude<< someLocation

Where can I find documentation/examples of the current test-subdir based
mechanism?

Yours,
Thomas

Toby Dylan Hocking wrote:
> First let me say that I can see where you're coming from. It would be
> beneficial to write examples right next to the function. In fact, this
> is the point of the inlinedocs package. However, putting them in
> comments using ##examples<< is not a solution I would be willing to
> use. How about the following solution, adapted from the fermat example
> (just look at the last few lines):
> 
> is.pseudoprime <- function#Check an integer for pseudo-primality to an arbitrary precision.
> ### A number is pseudo-prime if it is probably prime, the basis of
> ### which is the probabalistic Fermat test; if it passes two such
> ### tests, the chances are better than 3 out of 4 that \eqn{n} is
> ### prime.
> ##references<< Abelson, Hal; Jerry Sussman, and Julie
> ##Sussman. Structure and Interpretation of Computer
> ##Programs. Cambridge: MIT Press, 1984.
> (n, ##<< the integer to test for pseudoprimality.
>  times ##<< the number of Fermat tests to perform
> ){
>   result <- if(times==0)TRUE
>   ##seealso<< \code{\link{fermat.test}}
>   else if(fermat.test(n)) is.pseudoprime(n,times-1)
>   else FALSE
>   return(result)
> ### Whether the number is pseudoprime
>   is.pseudoprime(13,4)
> }
> 
> here we have a return() line explicitly in the function definition, so
> the code after it will never be executed when you actually use
> is.pseudoprime in your package. However, we will be able to parse the
> lines after it to use for examples. Kind of tricky, huh? I just got
> this idea and I like it!
> 
> advantages: 
> - example code is not commented, so easily testable and correctly highlighted
> - example code is right next to the corresponding function
> 
> disadvantages:
> - need to use explicit return
> 
> any other ideas?