[Linting Rule] Roxygen Arguments
This document was generated from 'src/documentation/wiki-linter.ts' on 2026-06-01, 20:20:18 UTC presenting an overview of flowR's linter (v2.10.6). Please do not edit this file/wiki page directly.
Roxygen Arguments [overview]
This rule is a best-effort rule.
Checks whether a function has undocumented or overdocumented parameters
This linting rule is implemented in src/linter/rules/roxygen-arguments.ts.
Linting rules can be configured by passing a configuration object to the linter query as shown in the example below.
The roxygen-arguments rule accepts the following configuration options:
#' A function with two parameters, but only only one documented
#' @param a A variable
f = function(a, b){return a;}The linting query can be used to run this rule on the above example:
[ { "type": "linter", "rules": [ { "name": "roxygen-arguments", "config": {} } ] } ]Results (prettified and summarized):
Query: linter (2 ms)
╰ Roxygen Arguments (roxygen-arguments):
╰ uncertain:
╰ Code at 3.5-29
╰ Metadata: searchTimeMs: 1, processTimeMs: 1
All queries together required ≈2 ms (1ms accuracy, total 3 ms)
Show Detailed Results as Json
The analysis required 2.6 ms (including parsing and normalization and the query) within the generation environment.
In general, the JSON contains the Ids of the nodes in question as they are present in the normalized AST or the dataflow graph of flowR. Please consult the Interface wiki page for more information on how to get those.
{
"linter": {
"results": {
"roxygen-arguments": {
"results": [
{
"certainty": "uncertain",
"involvedId": 10,
"loc": [
3,
5,
3,
29
],
"underDocumented": [
"b"
],
"overDocumented": []
}
],
".meta": {
"searchTimeMs": 1,
"processTimeMs": 1
}
}
},
".meta": {
"timing": 2
}
},
".meta": {
"timing": 2
}
}These examples are synthesized from the test cases in: test/functionality/linter/lint-roxygen-arguments.test.ts
Given the following input:
`#' This is a function.
#' An interesting function.
#' @param a some variable
#' @param b does not exist
f = function(a){return a;}`We expect the linter to report the following:
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(5, 5, 5, 26),
overDocumented: ['b'],
underDocumented: []See here for the test-case implementation.
Given the following input:
`#' This is a function.
#' An interesting function.
#' @param a some variable
f = function(a, b){return a;}`We expect the linter to report the following:
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(4, 5, 4, 29),
overDocumented: [],
underDocumented: ['b']See here for the test-case implementation.
Given the following input:
#\' This is a function.
#\' An interesting function.
#\' @param a some variable
#\' @param b does exist
f = function(a,b){return a;}We expect the linter to report the following:
* no lintsSee here for the test-case implementation.
Given the following input:
f = function(a){return a;}We expect the linter to report the following:
* no lintsSee here for the test-case implementation.
Given the following input:
f = function(){return 42;}We expect the linter to report the following:
* no lintsSee here for the test-case implementation.
Given the following input:
#\' @param a some variable
f = function(b){return b;}We expect the linter to report the following:
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(2, 5, 2, 26),
overDocumented: ['a'],
underDocumented: ['b']See here for the test-case implementation.
Given the following input:
#\' @param a some variable
f = function(){return 42;}We expect the linter to report the following:
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(2, 5, 2, 26),
overDocumented: ['a'],
underDocumented: []See here for the test-case implementation.
Given the following input:
#\' Just a comment
f = function(a){return 42;}We expect the linter to report the following:
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(2, 5, 2, 27),
overDocumented: [],
underDocumented: ['a']See here for the test-case implementation.
Given the following input:
#\' This is a function
f = function(){return 42;}We expect the linter to report the following:
* no lintsSee here for the test-case implementation.
Given the following input:
#\' @param h this is a param
f <- function(h){return h;}
#\' @inheritParams f
#\' @param t is random placeholder
g <- function(h,t){return h+t;}We expect the linter to report the following:
* no lintsSee here for the test-case implementation.
Given the following input:
#\' @param h this is a param
@param i another one
f <- function(h, i){return h;}
@param n another one
m <- function(h, i){return h;}
#\' @inheritParams f
#\' @inheritParams m
#\' @param t is random placeholder
g <- function(h,t){return h+t;}We expect the linter to report the following:
* no lintsSee here for the test-case implementation.
Given the following input:
#\' @param h this is a param
#\' @param k this is a param
f <- function(h, k){return h-k;}
#\' @inheritParams f
#\' @param t
g <- function(t,h,i){return h+t+i;}We expect the linter to report the following:
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(6, 6, 6, 35),
overDocumented: [],
underDocumented: ['i']See here for the test-case implementation.
Given the following input:
#\' @param a this is a param
#\' @param b this is a param
f1 <- function(a, b){return a-b;}
#\' @param c this is a param
#\' @inheritParams f1
f2 <- function(c, a){return c*a;}
#\' @inheritParams f1
#\' @inheritParams f2
#\' @param t is a param
#\' @param l is a param
f3 <- function(a,h,t,k){return h+t+i-k;}We expect the linter to report the following:
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(11, 7, 11, 40),
overDocumented: ['l'],
underDocumented: ['h', 'k']See here for the test-case implementation.
Given the following input:
#\' @param a this is a param
#\' @param b this is a param
f1 <- function(a, b, h){return a-b+h;}
#\' @param c this is a param
#\' @inheritParams f1
f2 <- function(c, a){return c*a;}
#\' @inheritParams f1
#\' @inheritParams f2
#\' @param t is a param
#\' @param l is a param
f3 <- function(a,h,t,k){return h+t+i-k;}We expect the linter to report the following:
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(3, 7, 3, 38),
overDocumented: [],
underDocumented: ['h']
},
{
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(11, 7, 11, 40),
overDocumented: ['l'],
underDocumented: ['h', 'k']See here for the test-case implementation.
Given the following input:
#\' @param h this is a param
#\' @param k another one
#\' @param l another one
f <- function(h, ...){return h;}We expect the linter to report the following:
* no lintsSee here for the test-case implementation.
Given the following input:
#\' @param h this is a param
f <- function(h, a,...){return h;}We expect the linter to report the following:
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(2, 6, 2, 34),
overDocumented: [],
underDocumented: ['a', '...']
},See here for the test-case implementation.
Given the following input:
#\' @param a this is a param
#\' @param b this is a param
f1 <- function(a, b, h){return a-b-h;}
#\' @inheritParams f1
#\' @param c this is a param
f2 <- function(c, ...){return c;}We expect the linter to report the following:
certainty: LintingResultCertainty.Uncertain,
loc: SourceRange.from(3, 7, 3, 38),
overDocumented: [],
underDocumented: ['h']See here for the test-case implementation.
Given the following input:
#\' @param ... this is a param
#\' @param a this is a param
f1 <- function(a, ...){return a;}
#\' @param b this is a param
#\' @inheritParams f1
f2 <- function(...){return 4;}We expect the linter to report the following:
* no lintsSee here for the test-case implementation.