[inlinedocs] inlinedocs

[Keith Ponting]

Hi Jim,

I like the idea of always overwriting - keeps things simple, but someone is sure to ask for the option not to sometime. Maybe we anticipate by documenting and telling them to keep the master as something else or just not use namespace=TRUE.

If you were able to put together a small package of use cases that would be a big help. When I have some time I will have a look and see how easy it is to work it in with what I did for setMethodS3. We should also add it to the inlinedocs tests...

With regard to new generics, I think we are in the territory of one of the options from the end of help("Documentation", package = "methods"), but I am not quite clear which... I think it would be good to take a look at what package.skeleton generates from your test package and kick around a bit what documentation should end up where. Looking closely both mypackage-class and show-methods end up with \alias{show,mypackage-method}, and only one will be accessed. 

Trying to understand this from the standard packages, I observe that method?show("signature") brings up the documentation for signature-class, which does not mention a show method, although one exists!!!

As a straw man, how about the following:
1) When a class is defined within the package, the "-class.Rd" file takes priority - remove the corresponding alias(es) from the "-methods.Rd" file, but put the method documentation in both files for completeness, so that someone studying "getAlignments" methods can see the details of all such methods (within one package) at one go, but someone studying a particular class sees the documentation of methods for that class.
2) When a new generic is defined within the package, the documentation for that generic has to live within the "-methods.Rd" file -- compare method?initialize("environment")
3) All other cases, such as a new generic within the package for a class defined somewhere else, also have to live within "-methods.Rd"

Note that my concept of "linked documentation" intended to inherit documentation of arguments from generic functions (_within_ the package) to more specific ones, so you do not have to repeat yourself for arguments which match the generic or even which match "earlier" specific ones. I am not totally convinced I have that right yet, as the concept of "earlier" is IIRC only defined within one source file.

Regards,

Keith

Keith Ponting
Aurix Ltd, Malvern WR14 3SZ  UK


> -----Original Message-----
> From: James Bullard [mailto:JBullard at pacificbiosciences.com]
> Sent: 30 April 2010 16:15
> To: Keith Ponting
> Cc: inlinedocs-support at r-forge.wu-wien.ac.at; toby.hocking at inria.fr
> Subject: RE: inlinedocs
> 
> 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