functions without parameter do not have usage? #35

Activity

1. statisfactions commented on Aug 29, 2011

   

   statisfactions

   on Aug 29, 2011

   More actions

   That line of code prevents inserting of a usage section for non-function objects (e.g. data or package). If we just remove that line and reinstall the package, we get problems when documenting data or packages:

   library(roxygen2)
   roc <- rd_roclet()
   
   out <- roc_proc_text(roc, "
       #' Data
       #' @docType data
       x <- 1:10")[[1]]
   roxygen2:::get_tag(out, "usage")$values

   With the proposed change, we will get x() for usage which will show up in the output Rd file, which is obviously not what we want for data.

   So we need another way of distinguishing function from non-function documentation if we want usage sections to come up for functions without parameter (and I agree this is a good thing!). One way to do this is to delete that line and replace it with:

   if(!is.null(partitum$docType)) return()

   With this change, if the user has used the @docType tag (i.e. package, data, or method/class for S4), which the user needs to pass R CMD check anyway for those kinds of objects, then this doesn't attempt to create usage from the function definition; otherwise it does even if there are no arguments. With that change in the code reinstalled in the package, my example produces NULL for usage and your example produces f().
2. yihui commented on Aug 30, 2011

   

   yihui

   on Aug 30, 2011

   ContributorAuthor

   More actions

   If there is a way to check whether the object is a function or not, it will be more straightforward to fix this issue. I did not dig deeply enough into roxygen2, so I do not know. Anyway, I believe your fix should work well. I cannot think of other cases that it can possibly fail.

   Thanks a lot!
3. hadley

   closed this as completedin c6f633eon Oct 25, 2011