3-documentation review

src/documentation.qmd

@@ -8,48 +8,57 @@ title: "Documentation"
 
 For your entire project, you will need a DESCRIPTION file which gather the project metadata, for instance:
 
+```
 > Package: mypackage
 > Title: What the Package Does (One Line, Title Case) \
 > Version: 0.0.0.1000 \
-> Authors@R: 
+> Authors@R:
     person("First", "Last", , "[email protected]", role = c("aut", "cre"),
            comment = c(ORCID = "YOUR-ORCID-ID")) \
 > Description: What the package does (one paragraph). \
 > Imports: Rpackage1, Rpackage2 (the list of R packages that are needed to run your analysis)
+```
 
+Some of these sections may be edited by hand, but others are automatically generated by `devtools` or `usethis` packages.
 
-## Function documentation: basics 
+## Function documentation: basics
 
 - What is needed in the function documentation?
 1. what does your function do
 2. with which arguments
-3. what does it return 
+3. what does it return
 4. (maybe) some examples of how to use it
 
-- Here is an example of header for the custom 'add' function: 
+- Here is an example of header for the custom 'add' function:
 ```r
-#' Add together two numbers 
-#' 
-#' @param x A number. 
-#' @param y A number. 
-#' @returns A numeric vector. 
-#' @examples 
-#' add(1, 1) 
+#' Add together two numbers
+#'
+#' @param x A number.
+#' @param y A number.
+#' @returns A numeric vector.
+#' @examples
+#' add(1, 1)
 #' add(10, 1)
-add <- function(x, y) { 
-  x + y 
+add <- function(x, y) {
+  x + y
 }
 ```
 
-- Write both function and documentation at the same time in my-function.R file, stored in R sub-repository.
+You can add many options to your documentation, such as:
+  - `@export` to make the function available to the user
+  - `@importFrom` to import a function from a package
+  - `@seealso` to refer to other functions
 
-- Use roxygen to generate man/my-function.Rd, reading the header: the devtools function document() 
+- Write both function and documentation at the same time in `my-function.R` file, stored in R sub-repository.
+
+- Use `roxygen` to generate `man/my-function.Rd`, reading the header: the `devtools` function `document()`
 ```r
 devtools::document()
 ```
-will generate (or update) your package’s .Rd files
+will generate (or update) your package’s `.Rd` files
+
+## Package documentation
 
-## Package documentation 
+For a more "integrated" documentation of your package, that details the functions, datasets, and other objects in your package, you can use [vignettes](https://r-pkgs.org/vignettes.html) that can generate webpages with interactive code, results, plots and comments, and [pkgdown](https://r-pkgs.org/website.html) to create a website for your package.
 
-For a more "integrated" manual, see vignette at <https://r-pkgs.org/vignettes.html>
- and website with pkgdown here <https://r-pkgs.org/website.html>.
+Also see [CI/CI page](ci_cd.qmd) to automate vignette and website publishing.