Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

functions without parameter do not have usage? #35

Closed
yihui opened this issue Aug 24, 2011 · 2 comments
Closed

functions without parameter do not have usage? #35

yihui opened this issue Aug 24, 2011 · 2 comments

Comments

@yihui
Copy link
Contributor

@yihui yihui commented Aug 24, 2011

Here is an example in which usage is NULL but should really be f():

library(roxygen2)
roc <- rd_roclet()

out <- roc_proc_text(roc, "
    #' Function without parameters
    f <- function() 1")[[1]]
roxygen2:::get_tag(out, "usage")$values

The fix seems to be to remove this line (I'm not sure): https://github.com/klutometis/roxygen/blob/master/R/roclet-rd.R#L405

@statisfactions
Copy link

@statisfactions statisfactions commented Aug 29, 2011

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().

@yihui
Copy link
Contributor Author

@yihui yihui commented Aug 30, 2011

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!

@hadley hadley closed this in c6f633e Oct 25, 2011
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Linked pull requests

Successfully merging a pull request may close this issue.

None yet
3 participants