search

EHDEN / Trajectories

5 stars 2 forks source link

[IMPROVEMENT] Documentation and Examples #35

Open smusali opened 1 year ago

smusali commented 1 year ago
  1. The Importance of Documentation: Good documentation is vital for any software project. It serves multiple purposes: it helps users understand how to use your package, it assists new contributors in getting up to speed, and it can even serve as a form of marketing by clearly communicating the benefits and capabilities of your package.
  2. R-specific Documentation Tools: Documentation is typically written in Roxygen2 format, a simple and intuitive way to document your code. Write the documentation in comments directly above the function definition, and Roxygen2 then generates the corresponding .Rd files automatically. This makes it easy to keep your documentation in sync with your code.
  3. Essential Components of Function Documentation: For each function, the documentation should include at least the following elements: a clear and concise title that explains what the function does, a more detailed description that explains the purpose of the function, how it works, and any essential considerations; a list of arguments with descriptions and expected types; a description of the output; and any errors or warnings that might be thrown.
  4. Writing Good Descriptions: Avoid jargon and complex terms as much as possible when writing descriptions. Also, remember that someone might be reading your documentation because they're stuck or confused, so try to anticipate their difficulties and address them directly. Your goal is to make your package accessible to as comprehensive an audience as possible.
  5. Including Examples: Including examples in your documentation is crucial. Examples help users understand how to use your functions and what to expect as output. Each function should have at least one example that demonstrates its primary usage. More complex functions may benefit from multiple examples that illustrate different use cases.
  6. Coverage of Examples: Your examples should cover a range of scenarios, including everyday use cases, edge cases, and potential error cases. This will help users understand the full capabilities of your functions and how to use them correctly.
  7. Testing of Examples: It's also good to test your examples to ensure they always work as expected. This can be done automatically with tools like the testthat package's expect_known_output() function, which checks that the output of an expression matches a previously recorded output.
  8. Package-level Documentation: Providing package-level documentation is important besides documenting individual functions. This should give an overview of the package, explain what it does and why someone might want to use it and provide a high-level guide to its structure and primary functions.
  9. Other Forms of Documentation: Besides the standard function and package documentation, consider other forms of documentation as well. This could include vignettes, which are longer-form guides that explain how to use your package in detail, and a website that presents your documentation in a more accessible format.