[inlinedocs] inlinedocs

[Keith Ponting]

Hi Jim, welcome to inlinedocs!

All packages must have a DESCRIPTION, so package.skeleton.dx generates a DESCRIPTION file if one does not exist. Otherwise IIRC everything package.skeleton.dx does goes into the "man" subdirectory.

NAMESPACE is different - not all packages have to have namespaces, although I am tending to use them more and more. Therefore we cannot high-handedly insist on generating one.

It would be useful and relatively trivial to add a "namespace" option to package.skeleton.dx, pass it to the embedded package.skeleton call and then copy the generated file into the correct place in the package source if it does not exist. 

The question is what to do about maintenance -- suppose I add a new class - it would be nice to automatically update the NAMESPACE file, but then what if I have separately edited the generated NAMESPACE file? Should we try and merge automatically, or warn the user and print a diff? I think my preferred route would be something like:
1) copy the generated NAMESPACE file to both <package>/NAMESPACE and <package>/NAMESPACE.autogenerated;
2) if those two files are still identical next time package.skeleton.dx is run with namespace=TRUE, then overwrite again;
3) otherwise print a warning message to the user showing the differences between autogenerated and existing NAMESPACE file.

There is also an incompleteness in the current handling of S4 class methods - I implemented something to cover the basic class definitions, but for each generic method the documentation might need to go in at least two places. For example, if I have a "show" method on class "results", then that is referred to both in "results-class.Rd" and in "show-methods.Rd". Both of these are generated by package.skeleton, so it might be useful to tuck the documentation into both places. However in my migration from S3 to S4 I have tended to write functions with S3-class-like names (e.g.) "show.results" then call setMethod("show","results",show.results) as opposed to writing the function definition inside that setMethod call, so that my documentation happily ends up under show.results. Therefore I am not sure which of the various options documented at the end of help("Documentation", package = "methods") are likely to be most sensible/useful...

Keith

Keith Ponting
Aurix Ltd, Malvern WR14 3SZ  UK


> -----Original Message-----
> From: Jim [mailto:jbullard at pacificbiosciences.com]
> Sent: 29 April 2010 17:38
> To: toby.hocking at inria.fr
> Subject: inlinedocs
> 
> Hi, I have started using your package inlinedocs and am having problems
> with S4 classes and generics. One thing I noticed is that in the auto-
> generated directory under pkgname/R/pkgname there is no NAMESPACE file.
> Is there a reason why this is not included?
> 
> 
> 
> I am the developer of the h5r package.
> 
> 
> 
> thanks, jim