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

[John Chambers]

"Marsland, John" wrote:
> 
> Might it be an idea to make "?" a special operator akin to "+" or "[", R
> users could then write their own help functions - may be even making "?"

In fact, "?" already is an infix operator ("grep '?' src/main/gram.y" to
see the grammar part of it).  Quite a bit of work has been done towards
making more general use of "?".  See help("?") for the general ideas. 
Class documentation is available this way:
  class ? numeric
  class ? MethodDefinition

For Version 1.8, there will very likely be some extensions.  These
require a bit of change to the "?" function itself to allow more general
expressions as arguments.  With that in place the current consensus (I
think) is to support expressions of the form:
  method ? f("numeric", "numeric")
to access method documentation for "f" corresponding to signature
c("numeric", "numeric"); and also of the form
  ?f(e1, e2)
for method documentation for the method selected corresponding to
expressions e1 and e2.

> generic? With the proposed xml help system one could imagine quite
> sophisticated context sensitive help systems.

Indeed.  There's been some nice work done.  One important question may
be finding the right balance between taking advantage of the nicer model
provided by XML and being compatible with current R documentation.

John

> 
> Regards,
> 
> John Marsland
> 
> PS this has been a very useful debate for those of us enthusiastically using
> S4 methods.
> 
> > -----Original Message-----
> > From: Duncan Murdoch [mailto:dmurdoch at pair.com]
> > Sent: 12 June 2003 18:54
> > To: Kurt.Hornik at wu-wien.ac.at
> > Cc: r-devel at stat.math.ethz.ch; Gordon Smyth; John Chambers
> > Subject: Re: Documenting classes and methods: was [Rd] Re: R-devel
> > Digest, Vol 3, Issue 23
> >
> >
> > On Mon, 9 Jun 2003 09:32:39 +0200, you wrote in message
> > <16100.14359.920512.374624 at mithrandir.hornik.net>:
> >
> >
> > >Re using 'foo-methods' as an alias, I am not sure whether this is
> > >necessary in the long run.  To find out which methods are
> > available, we
> > >can use showMethod().  We should eventually [see below] be able to do
> > >something like
> > >
> > >  method ? f(x="character", y = "numeric")
> > >
> > >to access the documentation object for the given signature,
> > and there is
> > >no guarantee that an f-methods Rd object really documents all methods
> > >for the generic f in the package.  So I think eventually we
> > should get
> > >rid of the default foo-methods alias, and just dump the ones
> > >corresponding to available methods.
> >
> > I hope that at this point we also implement
> >
> >  ?f(x,y)
> >
> > at this point, to give the same result (where x and y are existing
> > objects of classes "character" and "numeric", respectively).
> >
> > Duncan Murdoch
> >
> > ______________________________________________
> > R-devel at stat.math.ethz.ch mailing list
> > https://www.stat.math.ethz.ch/mailman/listinfo/r-devel
> >
> 
> **********************************************************************
> This is a commercial communication from Commerzbank AG.\ \ This ... {{dropped}}
> 
> ______________________________________________
> R-devel at stat.math.ethz.ch mailing list
> https://www.stat.math.ethz.ch/mailman/listinfo/r-devel

-- 
John M. Chambers                  jmc at bell-labs.com
Bell Labs, Lucent Technologies    office: (908)582-2681
700 Mountain Avenue, Room 2C-282  fax:    (908)582-3340
Murray Hill, NJ  07974            web: http://www.cs.bell-labs.com/~jmc