[inlinedocs] inlinedocs

[James Bullard]

Hi Keith, 

Thanks for the response. I make heavy use of NAMESPACES and S4 and I
have been actively looking for something to use for auto-doc generation.
I like the simplicity of inlinedocs.

In my opinion, no one should ever modify the generated files; similar to
javadoc and pydoc - once you can modify the generated versions then
you've lost one of the main benefits of the tool - consistency. I think
that you should just copy a NAMESPACE file over if it exists. 

As for the S4 handling. The documentation scheme within R is nearly
unmanageable so a tool to facilitate this is great. In response to your
point below, I tend to define the method directly in the setMethod call,
or at least I hide it behind the NAMESPACE.

Another thing that I do is create new generics. Currently, the
documentation engine dies because it doesn't know where the generic is.
The work around is to actually load the package which you are trying to
generate documentation for - not exactly appealing, but in most cases
this is probably okay - indeed R CMD check does this same thing. 

 Error in methods::promptMethods(item, filename = file.path(docs_dir,
sprintf("%s-methods.Rd",  : 
  No generic function found corresponding to "getAlignments"


Let me know how I can help, one thing I could easily do is put together
a small package with these use-cases and that might facilitate the
construction of these things -- if these are issues that you don't care
about then let me know and I'll try to see if there is something else,
or if I can roll this into your tool.

thanks again, jim


On Fri, 2010-04-30 at 04:37 -0400, Keith Ponting wrote:
> 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