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

All Rust code in extendr should be documented with rustdoc following conventions recommended in the Rust API Guidelines.

Doc examples that call the R API must be wrapped in with_r. Bare doctests without it will fail at runtime.

/// ```
/// use extendr_api::prelude::*;
/// with_r(|| {
///     let x = r!([1, 2, 3]);
///     assert_eq!(x.len(), 3);
///     Ok(())
/// });
/// ```

R Documentation

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

  • Roxygen documentation for every exported function must include the following roclets:
    • @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.
    • @examples
  • The @details section are optional, but should be included for most functions in rextendr.
  • 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.
  • In vignettes and online guides, use the extendrsrc and extendr knitr engines for examples involving Rust code. See user-guide/serde-integration.qmd for a worked example to emulate.