Function documentation - Brainstorm

[AndersAskeland]

Previous section

The preceding section is: sessions/function-development.qmd.

In this section, participants learn how to create functions that can be incorporated into R package.

Learning outcome

Overarching goal

• Learn why and how one document R functions utilizing {roxygen2}.

Sub goals

• Understand why function documentation is crucial for a package (exercise 1).
• Learn to document functions using {roxygen2} (exercise 2).
• Learn how to write and create examples within documentation (exercise 3).
• Familiarize with and apply various Roxygen tags (exercise 4).

Exercises

During exercise, improve previously written functions with what is learned.

Exercise 1 - The Importance of Documentation

Discuss why detailed documentation is vital. Focus on its impact on code readability, maintenance, and collaboration.

Exercise 2 - Documenting Functions with {roxygen2}

• Introduce the basics of using Roxygen for function documentation, covering essential aspects like the function's purpose, parameters (@param), return values (@return), and how to make a function available to users (@export).
• Explain export and when to use it.

Exercise 3 - Writing Effective Examples

• Learn about creating examples
• I am unsure: Is this not also used in/as unit testing?

Exercise 4 - Additional Roxygen Tags to Know

• Learn about additional Rozygen tags (reading exercise?)
  • @seealso: For linking related documentation or resources.
  • @family: To group related functions within the documentation.
  • @references: For adding citations to external sources or literature.
  • @note: To provide additional context or information.
  • @warnings: To alert users about any potential caveats or issues.
  • @inheritParams

Next...

??? Is it debugging?