Documenting classes and methods: was [Rd] Re: R-devel Digest, Vol 3, Issue 23

[Kurt Hornik]

>>>>> Gordon Smyth writes:

> Many thanks for your helpful comments.

> To over-simplify the previous discussion a bit, you are emphasising
> that all the aliases written by promptMethods will be needed by future
> versions of the help system, so it is important that they be included
> in .Rd files documenting methods. I was saying that these aliases are
> very verbose.

> I am not the only one having trouble with the aliases. I have looked
> through all the R packages that I know of that use S4 methods and
> can't find even one example of a documented method which preserves all
> the promptMethod style aliases. This may be partly because package
> authors aren't sure what they should be doing, but I think it has to
> be taken as a pretty strong statement from authors that the aliases
> don't produce a workable result with the online help system as it
> currently stands. The trouble I think is with the html package
> contents page, which very quickly becomes too long and cluttered to be
> useful if all the aliases are included.

> Could we satisfy both needs, (i) to have a unique help alias
> associated with each method and (ii) to have a package contents page
> which is readable, by giving authors control over which aliases are
> included on the contents page? Could we have a new command
> \aliasonly{} for the .Rd files for aliases which are to be available
> to the help system but not listed on the contents page? Authors could
> use \alias{} for aliases which are to be listed and \aliasonly{} for
> aliases which aren't.

> It might also be helpful to have an optional argument, as in
> \alias[optional.text]{}, to choose the text which is listed on the
> package contents page.

Ideas along these lines have already been discussed in considerable
detail within R Core ...

In any case, I am confused: by 'the contents page' you mean the
00Index.html files used by the HTML help system, and not the INDEX file
which could be rendered when asking for help on a package?

Afaic, this is primarily an implementation issue of the HTML help
system.  I do not know its internal workings, but it would seems to me
that when going

	Packages => mva

we should get an HTML version of the Rd *index* and not a list of all
the aliases with the titles (note that the index is generated from
name/title pairs).

Note that the HTML help system in its current layout cannot support
dynamic documentation.  It is my understanding that R Core has decided
to move towards the latter, with the obvious consequences for the
former.

-k