[inlinedocs] A bug and a suggestion for S3 methods support

[Philippe Grosjean]

Hello,

I played a little bit with inlinedocs, and found a couple of bugs. I 
propose corrections in the attached files (look for PhG in comments).

I propose also to add an argument in package.skeleton.dx() to create a 
name space, and the code for managing that. By the way, wouldn't you 
like to add a NAMESPACE to the inlinedocs package? It is much better 
when developing functions that depends on inlinedocs to rely on a name 
space!

The solution for S3 methods is not easy, because it is not obvious what 
is part of the generic and what is the object. The code in inlinedocs to 
automatically detect S3methods in the case of R.oo objects will fail if 
the generic has one or more dots, like in as.data.frame.matrix(), where 
the generic is 'as.data.frame', and the object is 'matrix'. Your current 
code will calculate 'as' as the generic and 'data.frame.matrix' as the 
object. Although it is not automatic, I think that a simple tag like:
##S3method<<as.data.frame
somewhere inside the body of the function makes the job. It is also used 
to create S3method(generic, object) statements in NAMESPACE file, if 
that one is requested (see hereover). It should be possible to detect 
automatically S3 methods, but that is tricky, and the proposed method is 
much simpler!

You patch for 'examples.after.return' does not solve the problem 
completely. Indeed, it is hard (if not impossible) to have a good 
detection of the end of the function code and the beginning of the 
example code. Think that you may have multiple return() statements in a 
function (you code will split after the first one, sic!). And, in case 
you decide to split after the last return(), think that you could also 
have return() statement in some 'examples' code! Gasp!

I propose a very different method to embed 'examples' code in a 
function: to use an 'ex' attribute for the object. I have written a 
parser 'examples.in.attr' which makes 4 lines of code only. It works 
well. The way you define examples for your functions is a little bit 
more tricky, but one should survive... What do you think of this?

It has also two benefits over your approach to be usable to attach 
'examples' to any objects, including datasets (in case inlinedocs 
bacomes capable of documenting datasets in the future).

- External examples should be located in /tests/fun.R, but I argue that 
it is perhaps not optimal in all cases (see comments in the code). So, 
for not breaking current behavior but to allow for another location of 
these files, too, I propose to use the option(inlinedocs.exdir = ...). 
Code is written in the attached files to deal with that option.


Among the bugs corrected:
- Wrong .Rd file names for functions like 'obj<-', and others (now, it 
uses exactly the same code as package.skeleton() to determine the name 
of the .Rd files),

- Wrong treatment of platform-specific code in /R/unix, or /R/windows. I 
propose code that detects the presence of these subdirectories and 
stop() with an explicit message in such a case,

- Bad formatted error message with
stop("Need ",names(f)[f]," in ",descfile)
in case there are several items, one should use something like:
stop("Need ", paste(names(f)[f], collapse = ", "), " in ", descfile)
(corrected in two places),

- inlinedocs failed to use information in 'Imports' field (corrected),

- wrong extraction of package names form 'Depends' field in case where 
packages contain one or more dots in their names (corrected),

- It is necessary to eliminate 'R' from the list of packages to load 
from 'Depends' field (corrected),

- It is not useful to try to load packages that are already loaded 
(corrected),

- inlinedocs did not detach packages that were not loaded before its 
call when it returns (corrected, including unloading of their 
namespaces, if possible),

- A possible 'Encoding' field in DESCRIPTION also means the default 
encoding of .R files... and this was not taken into account by 
inlinedocs (corrected),

- in \usage, generic<-.obj(x, ..., value) must be rewritten 
\method{generic}{obj}(x, ...) <- value  (done),

- in \usage, fun<-(x, ..., value), must be rewritten fun(x, ...) <- 
value (done),

- in \usage, %...%(x, y) must be rewritten x %...% y. Code is there, but 
I end up with an empty \usage section => ???

I have asked on R-Forge to participate to the development of inlinedocs. 
If you think it is fine, and you would prefer I submit these patches (or 
some of them) directly in the SVN on R-Forge, I could do that... just 
add me as a developer on the project ;-)

Best,

Philippe

..............................................<°}))><........
  ) ) ) ) )
( ( ( ( (    Prof. Philippe Grosjean
  ) ) ) ) )
( ( ( ( (    Numerical Ecology of Aquatic Systems
  ) ) ) ) )   Mons University, Belgium
( ( ( ( (
..............................................................

On 14/05/10 21:00, Toby Dylan Hocking wrote:
> Hi, thanks for the helpful comments, and I'm glad to hear you like
> using inlinedocs.
>
> I was not able to reproduce the exact same error you had, but I see
> what was happening, and I think I fixed it. The bugfix has been
> checked in to SVN, rev 102, if you'd like to test it and make sure it
> works on your end.
>
> Thanks for the insightful point about S3 methods. We have talked about
> generating proper \method markup for S3 methods on the list before,
> but I haven't got around to it yet since it doesn't generate a warning
> in R CMD check. Keith wrote some support for setMethodS3()
> definitions, but I don't really use it, so maybe Keith would have a
> better idea of if it would be feasible anytime soon. It would be nice
> if we could automatically detect methods and avoid having to write
> something like ##<<method<<print<<object. In any case, if you manage
> to write some code (maybe a new parser function?) that makes correct
> S3 method markup for the usage section, please tell us about it.
>
>
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: package.skeleton.dx.R
URL: <http://lists.r-forge.r-project.org/pipermail/inlinedocs-support/attachments/20100517/bf2406b3/attachment-0001.txt>
-------------- next part --------------
An embedded and charset-unspecified text was scrubbed...
Name: parsers.R
URL: <http://lists.r-forge.r-project.org/pipermail/inlinedocs-support/attachments/20100517/bf2406b3/attachment-0001.asc>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: inlinedocsTest.zip
Type: application/zip
Size: 12301 bytes
Desc: not available
URL: <http://lists.r-forge.r-project.org/pipermail/inlinedocs-support/attachments/20100517/bf2406b3/attachment-0001.zip>