[inlinedocs] feature suggestions

[Toby Dylan Hocking]

Hi Claudia, and thanks again for your thoughtful comments.

Personally I prefer the inline example documentation style to both the
"examples(f)<-" and 'attr(f,"ex")<-' style. I agree that
"examples(f)<-" is more intuitive. And yes the package author should
be free to do as he/she pleases! However, I don't understand exactly
what you are suggesting, when you talk about svTest and say

"But it doesn't need a dependency: at the moment it lives in the first
file of the package that is sourced."

Then you suggested 2 ways to fix the NAMESPACE problem:

A) the combination of
- no documentation comments => no .Rd and
- not exported => no .Rd

B) the combination of
- a doc comment to suppress generation of .Rd
- a doc comment that triggers whether the function is listed in the
- exports of NAMESPACE
(as Roxygen does it)

I don't write packages with private (non-exported) objects so I don't
really have the problems you are describing. I would prefer solution
(A) that you described, since it is simpler and doesn't require any
new comment syntax. I think an elegant fix would be to just introduce
a new parser function that deletes items from the documentation list
if they are not exported according to NAMESPACE. Then use the rule
that if there's nothing in the documentation list, then don't make
that Rd file. However I will have to edit some code in modify.Rd.file
to make this work, so it would be useful to have a test case. I added
you to the project, so the easiest thing for me would be if you just
upload the code that gives you an error to
inlinedocs/pkg/inlinedocs/tests in the subversion repository.

I'm glad to hear that you see more important additions to inlinedocs,
and if you find some time to contribute in the future I would be more
than happy to have your contributions, so feel free to commit them and
discuss on the list when you have the time.