fusen

fusen copied to clipboard

I did two functions that share the same parameters (say_hello and say_goodbye). I added #' @rdname explicitly to both and they were recognized as properly documented. I think you can safely do the following: Take the first function name as the name of the function_file.R create @rdname entry for this function and repeat it for every function in this chunk. This will ensure that parameters are shared and have to be documented only once. Examples chunk that follows can contain examples of both functions, even though the #' @examples roxygen tag is also honored (I managed to have a function which has examples in 3 places, inside each function and again in the special chunk. Downside, of course, is that the roxygen-documented examples will not end up in the vignette. I understand that you are adding things to roxygen tags, but not really parcing existing roxygen content. (edited)

This would require that people use both function in the same chunk on purpose. But that makes sense. At worst, I can add a message saying that these function are supposed to be from the same family and will share the same documentation.

naming the file by the first function name is an OK idea. Couple of other options:

1. Allow custom naming of chunks, as long as they contain the prefix: i.e. function-norm and function-beta-binom are valid chunk names. The prefix function- will be stripped and the rest will be used as the name of the file for the function. Chunk prefixing could also be useful in test- as the postfix could be used as a tag for the context() but now that it is deprecated, you can name the test file using the content of the postfix.
2. Teach the people to use the @name tag and reuse it for rdname.

As you can tell I like to keep related function together in my packages and I hate documenting arguments in multiple places. Hence, the request.

Similarly, how to group function- chunks in the same "R/" file, like test- chunks in the same "tests/" file in an elegant way ?

I have to find the right approach.

• The @rdname is one way, but it also combines the roxygen doc, which is not really what we want to achieve.
• The @family tag is another way, but it cross-references documentation in See Also, which may not be a wanted way either.
• Maybe we can add a chunk parameter instead with main = "name-of-the-function" or parent or ..., but this adds a new parameter that knit may not like if users put that in examples chunks too.
• Or if we put the same chunk name function-my_function, we could do something to put in the same file, but then it prevents the use of nice chunk names to navigate into
• Or decide that if it's a level 1 title, then it's in the same file, but it has to be clear to the devs. For the moment nobody has understood that it's the title levels that separate the functions... :smile:

I guess the possibility to regroup functions under the same file as described in the doc is enough: https://thinkr-open.github.io/fusen/articles/tips-and-tricks.html#how-to-store-multiple-functions-in-a-unique-r-file