search

colearendt / tidyjson

Tidy your JSON data in R with tidyjson
Other
182 stars 14 forks source link

Help files included for many non-exported functions #105

Closed agwells closed 4 years ago

agwells commented 6 years ago

I love this package, it really speeds up the process of tidying my JSON inputs! :)

But, I noticed that when I do help(package="tidyjson"), there are a lot of help files listed for functions and objects that are not exported. For instance tidyjson::prep_path. This makes the package help a little confusing, because there are many entries that aren't helpful for me as an end-user.

I believe the cause is that the package contains roxygen2 docblocks (lines starting with #') for many non-exported items, and roxygen2 always includes all docblocks in its output, whether they're for exported thigns or not. This surprised me, because I'm used to JSDoc, which allows you to choose which docblocks to included in automated documentation; so that you can build "developer docs" that include all docblocks, and "user docs" that exclude those with tag @private.

If you want to retain all those inline docblocks for the non-exported items, I think there may be a workaround, if you use the @rdname tag to place them all in a file named eg internal.Rd, and then add that file to .Rbuildignore.

colearendt commented 6 years ago

This is a great call, and might be worth a feature request to roxygen. What you propose may be the common practice for excluding internal docs from the package output.

agwells commented 6 years ago

Okay, I've filed an issue about it over on the Roxygen page. :)

colearendt commented 6 years ago

Alrighty! Per https://github.com/klutometis/roxygen/issues/684 , @keywords internal need to be added to internal function roxygen definitions.