[inlinedocs] new inline example ideas

[Toby Dylan Hocking]

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?