Documenting Code

Code in extendr and rextendr should be thoroughly documented using widely accepted styling conventions in the R and Rust communities.

Writing style

  • Be concise! And stay on topic! The reader should not have to wade through lengthy digressions to get to the point.
  • Eschew obfuscation and avoid needlessly wordy phrases like ‘eschew obfuscation.’ In other words, keep it simple.
  • Second person (“you”) is fine for instructions, but do not write about the reader’s intentions in the second person (avoid expressions like “you want to” or “you need to”).

Rust Documentation

R Documentation

Functions in rextendr should be documented with roxygen2, following the conventions recommended by the tidyverse style guide.

  • Every exported function in rextendr must include the following roxygen variables:
    • @title
    • @description — a concise description of what the function does.
    • @param — one tag per parameter, specifying:
      • the data type (e.g. integer, character, logical)
      • whether it is a scalar or vector
      • the default value, if one exists
    • @return — what the function returns, including the R type.
  • The @details and @examples sections are optional, but should in general be included.
  • Internal functions should include roxygen comments if their use in rextendr is fairly complex, important, and not easy to discern. Simple helper functions do not need to be documented.