[Roxygen-devel] S4 implementation of @usage

[Vitalie Spinu]

I have done my best here https://gist.github.com/3516476

In what follows, I use the same names as in my gist outline, in an
attempt to influence you in the naming matter of course ;).

  >> Hadley Wickham <hadley at rice.edu>
  >> on Wed, 29 Aug 2012 12:25:19 -0500 wrote:

  > Object seems a bit awkward because it's part of the rocblock, and is
  > currently stored in a list with it's value and it's name. But I don't
  > see how you'd dispatch on it, unless you pull it out into a separate
  > argument.

Yes, dispatch is on the object which is part of rocblock (maybe
roxyBlock?). roxyParse is used only internally, so not a big deal. When
iterating, disassembling and calling roxyParse(rblock at object), rblock at doc)
looks fine to me.

  > I find the approach of having a pre-parsing phase much easier to test,
  > which is why I generally prefer it.

Agree, I also find it more transparent. Another way (as I noticed in my
gist) is to allow the roxyParse method to alter the global object
RoxyPackage which contains all the roxyBlocks. Then you might not even
need preParsing stage. (BTW, preParsing should be also a method,
roxyPreParse).

  >> > Currently the roccer implements the strategy design pattern so that
  >> > you can separately specify the parser and the output. How would you do
  >> > the same with S4?  Multiple inheritance?
  >> 
  >> This are methods for each tag. You must have rocParse method and rocRd
  >> method, that's all. Not rocOut, you will pretty soon have rocHTHL,
  >> rocMarkdown etc to output into other formats. (maybe outputRd,
  >> outputHTML etc).

  > Hmmm, so to define a new type of output, you define a new generic like
  > OutRd, OutNamespace,  OutDescription etc.  

I am not really following. outNamespace, OutDescription are global
processing on the whole package. They are not tag, object or roxyDoc
specific. 

If so, then there is no need for methods. They are just functions taking
one argument (roxyPackage in my terminology). One only need methods for
tag, doc and object specific tasks.
 
  > The methods would then return objects that give information so that
  > the Out object can put them in the right class. For Rd this is a
  > file name and some rd commands, for namespace it's a character
  > vector of lines, for description it's named fields (probably just
  > strings).

Hm, may be I am misunderstanding something. outRd is a method which
produces the documentation (Rd) file from a roxyDoc object and the
object itself. This is how I understand it.

You seem to talk about some intermediary stage for which I don't really
see the rationale, but may be it's just terminological issue.

        Vitalie