On Thu, Aug 30, 2012 at 2:12 PM, Vitalie Spinu <spinu...@gmail.com> wrote: > >> Hadley Wickham <had...@rice.edu> > >> on Thu, 30 Aug 2012 11:29:07 -0500 wrote: > > > >> So roxygenize will iterate 3 times over all tags and call prepareTag on > >> first iteration, then prepareDoc, and finally preparePackage. > > > That's better, but generally you only need to call preparePackage > > once, not once for each instance of that tag. > > No, no ... that was precisely the main point! It should process each > *tag* at "package level". Then process each *tag* at a "block level" and > finally at "tag level". Here is the complete pseudo code for roxy > package:
Hmmmm, that's an interesting approach. I had another idea, and that was that what I was calling a GlobalTag is originally what I was calling a Roccer - i.e. it's something that takes a RoxyPackage as input and a RoxyPackage as output. Then it would be a clean separation: RoxyTags act locally (at the RoxyBlock level) and Roccers act globally (at the RoxyPackage level). I think it makes sense to make this distinction because the process you outline below doesn't quite fit the common Roccer (e.g. family, inheritParams, include) scenario which typically involves two passes: the first to built up a datastructure that stores information about the global structure, and the second that goes through and modifies individual RocBlocks. I also think it seems wrong to have a generic called procPackage - why do you have the name of the class it operates on in the generic name? > roxygenise <- function(...., ## see below for explanation > processors = c(procRd, procNamespace, procCollate, > procMyCoolIndex)){ > roxypkg <- parse_all_files(...) > > roxypkg <- procPackage(roxypkg) > > for ( proc in processors ) > roxypkg <- proc(roxypkg) > > } I was thinking of something like roxygenise <- function(..., tags, roccers, outputs) { pkg <- roxy_init(...) # not an S4 method because it starts the ball rolling pkg <- roxyProcess(pkg, tags) pkg <- roxyProcess(pkg, roccers) roxyWrite(pkg, outputs) } where if not specified tags, roccers and outputs would default to finding all classes that inherited from the appropriate base class. > > I don't think that can work, because combining Rd commands can't work > > at the string level, and it varies from command to command. i.e. if > > you have multiple @keywords you do > > > \keyword{one} > > \keyword{two} > > \keyword{three} > > > but for multiple @params you do > > > \arguments{ > > \item{one}{desc one} > > \item{two}{desc two} > > } > > Good example. Let me fit it into the above paradigm. > > After the *block level* processing this RoxyBlock will have a tag of > class "TagArguments" (and *no* tags of class TagParam). That is, it is a > *standalone* entity which can be transformed by outRd into a string. > > In other words, TagParam's roxyProcess *block level* method creates a tag > @arguments and removes the corresponding TagParam argument from the > roxyBlock object. Problems: * calling it "block" level doesn't really make sense because it's now (potentially) working on multiple blocks * what happens to the objects? Does each RoxyBlock now have a list of objects associated with it? If so, how do you associate the usage statements with the objects. i.e. how would you resolve: #' Topic a. #' #' @rdname shared a <- function(x) {} #' Topic b. #' #' @rdname shared #' @usage b() # some comment here b <- function(x) {} > > If you did it with different methods (outRd, outNamespace, > > outDescription), and the user created a new type of output (e.g. > > outDemoIndex) how would they tell roxygen to all call the outDemoIndex > > on every block/tag? > > Good point. I think your solution of passing processing functions to > roxygenize should work best: > > roxygenize( ..., output = c(outRd, outCollate, outNamespace, outDemoIndex)) > > where outRd, outCollate, outDemoIndex are function *or* generics which > roxygenize will call on the RoxyPackage object. First procPackage > should be called, and then all the "outputers" in turn. All of them > should return back an object of class RoxyPackage which will be passed > to the next processor in the chain. > > BTW, why "output"? I find this name confusing. This functions can have > arbitrary side effects, or just change the content of the RoxyPackage > object. That's an interesting observation - the output objects have basically the same semantics as the roccer objects. But I think there are some important differences: * Output objects are used solely for their side effects (writing to disk). They return nothing. * Roccer objects return a modified RoxyPackage and have no side-effects. This is important for testing. * All roccers need to be run before output can occur. > > But output does differ between tags? Some need to output Rd, some > > NAMESPACE, etc. > > BTW, is it a tag task to generate namespace? Isn't it that RoxyDoc's method > should generate it. It's the tags task to say where it's output should go - it shouldn't modify the file on disk, but it should provide the output in suitable format for writing. > > Hmmm, but you list rd, html and text as potential output formats - I > > definitely don't see html and text as output types. That's something > > you might generate from the Rd files, but I don't think it's the job > > of roxygen to generate anything that R doesn't use directly. Maybe > > that's why we seem to be talking past each other. > > You are right. I am confused. And my confusion stems from the "output" > terminology which I have hard time to get used to. Somehow it really > doesn't sound right to call a namespace generator, an output. outCollate > is even more weird. I think of it as an output in the same sense that the RoxyBlocks (or RoxyPackage) are inputs - everything else is just an intermediate form. The user only sees what the Output objects do. Hadley -- Assistant Professor Department of Statistics / Rice University http://had.co.nz/ _______________________________________________ Roxygen-devel mailing list Roxygen-devel@lists.r-forge.r-project.org https://lists.r-forge.r-project.org/cgi-bin/mailman/listinfo/roxygen-devel