[inlinedocs] new inline example ideas

[Toby Dylan Hocking]

Hi Thomas, and thanks for the input. First of all, let's adopt a
standard naming scheme for discussing the 3 different methods for
writing examples:

tests-folder          (current method)
examples-after-return (new method I proposed last week)
##examples<<          (writing examples in comments)

I will respond point by point.

You can find a simple example of the tests-folder method in
inlinedocs/tests/fermat, which is a simple package with a tests/
subdirectory and a simple example. When you run package.skeleton.dx()
on it, you should get a man/is.pseudoprime.Rd file with an example.

Yes, I agree that my proposed examples-after-return style of inline
examples would be confusing at first.

I don't use RUnit, but I just read its vignette and I don't think this
should pose any problems. For the code inspection that it claims to do
I suspect that the code in examples-after-return will just not get
executed.

Your proposed ##examplesInclude<<filename method is redundant with the
current tests/ subdirectory method. Essentially it is a question of
convention over configuration. Right now we have the convention of
getting examples from tests/FUN.R. Or do we want to allow
configuration of which file has tests for each function? I prefer
convention over configuration here, and I would not like to support
##examplesInclude<<

As for the examples-after-return method, here are the pros and cons:

Advantages
1. examples very close to function definition
2. you don't have to repeat the function name to
   define the examples for it
3. example code is not commented

Disadvantages
1. need to use explicit return
2. may be confusing

The current method of examples using the test subdirectory is only
there because it was easy to implement and I didn't have any other
ideas. However the whole point of inlinedocs is to write your code and
documentation right next to each other. With that in mind, I believe
the new examples-after-return approach is the most aligned with the
spirit of the package.

That being said, it seems like the ##examples<< method is also aligned
with the spirit of the package. In particular it has advantages 1. and
2. but the disadvantage that code is commented. It should be easy to
implement, so I say go for it if you like. It seems less sustainable,
though, so I don't plan on using it.