Add examples for @rdname to 'reuse' vignette #1496
Conversation
|
Thanks for getting me started on this. Can you take a look at my revisions and let me know if they make sense to you? |
vignettes/reuse.Rmd
Outdated
| The functions will be collected and share the same `@title`, `@description`, `@examples`, etc. | ||
|
|
||
| There are two basic ways to use it. | ||
| You can create a dummy documentation block and then add the functions to it. |
There was a problem hiding this comment.
nit: recently have been avoiding the term 'dummy' (e.g. https://blog.leeandlow.com/2012/08/16/when-did-the-word-dummy-become-derogatory/ / https://source.android.com/docs/setup/contribute/respectful-code#term-examples / https://nvlpubs.nist.gov/nistpubs/ir/2021/NIST.IR.8366.pdf), usually 'placeholder' serves the purpose equally well.
There was a problem hiding this comment.
Good point. And I think "standalone" is more clear here anyway.
| #' @export | ||
| ln <- function(x) log(x, exp(1)) | ||
| ``` | ||
|
|
There was a problem hiding this comment.
do we need #' @export tags in the next section (L94-103)?
| ``` | ||
|
|
||
| Alternatively, you can add docs to an existing function. | ||
| This tends to work better if you have a "primary" function with some variants or some helpers. |
There was a problem hiding this comment.
I'm not sure we're quite there yet, now we have in @rdname
This tends to work better if you have a "primary" function with some variants or some helpers.
Vs in @describeIn
You can document several functions which perform slight variations of a task or which use different defaults
Do we need to distinguish these two "variant"/'variation" use cases further? Or are they ~somewhat~ interchangeable?
There was a problem hiding this comment.
TBH I've mostly forgotten what @describeIn does and why you might use it. I think the main difference is that it attempts to build the single description for you by creating a bulleted list. But I'm not sure this is now possible to do in a compelling way, and I think you're generally better off using @rdname with a custom @description.
There was a problem hiding this comment.
That seems reasonable enough to me. OTOH, as someone looking at a lot of other peoples' code, it's something I come across fairly often -- it would be nice to point to a canonical reference during code review urging one or the other in each case.
I see 1000s of usages on CRAN:
https://github.com/search?q=lang%3AR+%2F%23%27%5Cs%40describeIn%2F+org%3Acran&type=code
Here's the only file with usage in tidyverse:
Vs. 10 packages using it from r-lib:
https://github.com/search?q=lang%3AR+%2F%23%27%5Cs%40describeIn%2F+org%3Ar-lib&type=code
There was a problem hiding this comment.
Ok, I've made it more clear that I don't recommend it, and I'll fix the reprex usage momentarily.
|
Thanks! |
Closes #1495.
I am far from an expert here, and only have a vague sense of when to use one vs. the other myself. The "vibe" I have is
@rdnameis better when the functions will be "on equal footing" on the shared page, where as@describeInis more apt for "corollary methods" of a main topic. If that's right, it may be useful to convey that in these sections as well.