Even as a total newbie to R package development, I know I should not manually edit files in man/ folder most of time ... Hence, this check list should be used together with #22.
Instead of writing these files by hand, we’re going to use roxygen2 which turns specially formatted comments into .Rd files.
[ ] Follow the documentation workflow: 1-2-3-4 or 1-2-3-4
[ ] Roxygen comments start with #' and come before a function.
[ ] Each line should be wrapped in the same way as your code, normally at 80 characters.
[ ] Because @ has a special meaning in roxygen, you need to write @@ if you want to add a literal @ to the documentation.
[ ] The first sentence becomes the title of the documentation.
[ ] The second paragraph is the description: this comes first in the documentation and should briefly describe what the function does.
[ ] The third and subsequent paragraphs go into the details: this is a (often long) section that is shown after the argument description and should go into detail about how the function works.
[ ] All objects must have a title and description. Details are optional.
[ ] You can add arbitrary sections to the documentation with the @section tag. This is a useful way of breaking a long details section into multiple chunks with useful headings. Section titles should be in sentence case, must be followed by a colon, and they can only be one line long.
[ ] @seealso allows you to point to other useful resources, either on the web, \url{http://www.r-project.org}, in your package \code{\link{functioname}}, or another package \code{\link[packagename]{functioname}}.
[ ] If you have a family of related functions where every function should link to every other function in the family, use @family. The value of @family should be plural.
[ ] @aliases alias1 alias2 ... adds additional aliases to the topic. An alias is another name for the topic that can be used with ?.
[ ] @param name description describes the function’s inputs or parameters.
[ ] The description should start with a capital letter and end with a full stop. It can span multiple lines (or even paragraphs) if necessary. All parameters must be documented.
[ ] Can document multiple arguments in one place: @param x,y Numeric vectors..
[ ] @examples provides executable R code showing how to use the function in practice.
[ ] Example code must work without errors as it is run automatically as part of R CMD check.
[ ] \dontrun{} allows you to include code in the example that is not run.
[ ] Can put them in separate files and use @example path/relative/to/package/root to insert them into the documentation. (Note that the @example tag here has no ‘s’.)
[ ] @return description describes the output from the function.
[ ] Indent the second and subsequent lines of a tag so that when scanning the documentation it’s easy to see where one tag ends and the next begins.
[ ] Can use roxygen to provide a help page for your package as a whole.
[ ] Document S3, S4 and RC.
[ ] Special characters: @@ for @, %% for % and \\ for \.
[ ] There is a tension between the DRY (don’t repeat yourself) principle of programming and the need for documentation to be self-contained.
[ ] Inherit parameter descriptions from other functions using @inheritParams source_function and or @inheritParams package::function.
[ ] Document multiple functions in the same file by using either @rdname or @describeIn.
Below is a check list of guidelines on files in
man/from Wickham's package book: http://r-pkgs.had.co.nz/man.htmlEven as a total newbie to R package development, I know I should not manually edit files in
man/folder most of time ... Hence, this check list should be used together with #22.#'and come before a function.@@if you want to add a literal@to the documentation.@sectiontag. This is a useful way of breaking a long details section into multiple chunks with useful headings. Section titles should be in sentence case, must be followed by a colon, and they can only be one line long.@seealsoallows you to point to other useful resources, either on the web,\url{http://www.r-project.org}, in your package\code{\link{functioname}}, or another package\code{\link[packagename]{functioname}}.@family. The value of@familyshould be plural.@aliases alias1 alias2 ...adds additional aliases to the topic. An alias is another name for the topic that can be used with?.@param name descriptiondescribes the function’s inputs or parameters.@param x,y Numeric vectors..R CMD check.\dontrun{}allows you to include code in the example that is not run.@example path/relative/to/package/rootto insert them into the documentation. (Note that the@exampletag here has no ‘s’.)@return descriptiondescribes the output from the function.@@for@,%%for%and\\for\.@inheritParams source_functionand or@inheritParams package::function.@rdnameor@describeIn..Rdsyntax to format text: https://cran.r-project.org/doc/manuals/R-exts.html#Marking-text