R Language Meta: Documentation Guidelines Style


Example

Prompts

If you want your code to be copy-pastable, remove prompts such as R>, >, or + at the beginning of each new line. Some Docs authors prefer to not make copy-pasting easy, and that is okay.

Console output

Console output should be clearly distinguished from code. Common approaches include:

  • Include prompts on input (as seen when using the console).
  • Comment out all output, with # or ## starting each line.
  • Print as-is, trusting the leading [1] to make the output stand out from the input.
  • Add a blank line between code and console output.

Assignment

= and <- are fine for assigning R objects. Use white space appropriately to avoid writing code that is difficult to parse, such as x<-1 (ambiguous between x <- 1 and x < -1)

Code comments

Be sure to explain the purpose and function of the code itself. There isn't any hard-and-fast rule on whether this explanation should be in prose or in code comments. Prose may be more readable and allows for longer explanations, but code comments make for easier copy-pasting. Keep both options in mind.

Sections

Many examples are short enough to not need sections, but if you use them, start with H1.