documentation_linters {roger}

Validation of Documentation

Description

Check for comments and proper documentation of a function in a script file.

The expected documentation format is not unlike R help pages; see details.

Usage

any_comments(srcData, ...)

any_doc(srcData, ...)

signature_doc(srcData, ...)

section_doc(srcData, pattern, ...)
description_section_doc(srcData, ...)
arguments_section_doc(srcData, ...)
value_section_doc(srcData, ...)
examples_section_doc(srcData, ...)

formals_doc(srcData, ...)

Arguments

srcData

a list as returned by getSourceData.

pattern

character string containing a regular expression describing a keyword to match in the documentation.

...

further arguments passed to grepl.

Details

any_comments checks that a script file contains at least one non empty comment, that is, a string with at least one character other than whitespace after the comment delimiters.

The other functions check the documentation provided with function definitions in a script file. Comments starting in column 1 are considered documentation.

any_doc checks that the file contains some documentation.

signature_doc checks that the signature (or usage information) of every function is present in the documentation.

section_doc checks that the documentation contains a section title corresponding to pattern for every (or as many) function definition. Functions description_section_doc, arguments_section_doc, value_section_doc and examples_section_doc are wrappers for common patterns Description, Arguments?, Value and Examples?, respectively.

formals_doc checks that the description of every formal argument is present in the documentation.

Value

Boolean. When FALSE, a message indicates the nature of the error, and the returned value has the following attributes:

nlines

number of lines checked for comments or documentation (any_comments and any_doc only);

fun

names of functions without a signature in the documentation (signature_doc only);

sections

number of sections missing from documentation (section_doc and wrapper functions only);

formals

formal arguments missing from documentation (formals_doc only);

message

text of the error message.

References

Goulet, V., Programmer avec R for the standard documentation format these functions were developed for.

Examples

## Keep parse data in non interactive sessions.
if (!interactive())
    op <- options(keep.source = TRUE)

## Script with non empty comments.
fil <- tempfile(fileext = ".R")
cat(file = fil, "
#-
## here is foo
#-
foo <- function(x, y = 2)
    x + y  #addition
")
any_comments(getSourceData(fil))

## Script with embedded documentation.
fil <- tempfile(fileext = ".R")
cat(file = fil, "
###
### foo(x, y = 2)
###
##  Adding two vectors
##
##  Arguments
##
##  x: a vector
##  y: another vector
##
##  Value
##
##  Sum of the two vectors.
##
##  Examples
##
##  foo(1:5)
##
foo <- function(x, y = 2)
    x + y
")
fooData <- getSourceData(fil)

## Elements present in the documentation
any_comments(fooData)
any_doc(fooData)
arguments_section_doc(fooData)
value_section_doc(fooData)
examples_section_doc(fooData)
formals_doc(fooData)

## Missing section title
description_section_doc(fooData)