dan/oxc
1
0
Fork 0
mirror of https://github.com/danbulant/oxc synced 2026-05-19 12:19:15 +00:00
Code Issues Projects Releases Packages Wiki Activity Actions

feat(linter/jsdoc): Implement require-returns-description (#3397)

Browse source 
Part of #1170 

>
https://github.com/gajus/eslint-plugin-jsdoc/blob/main/docs/rules/require-returns-description.md
This commit is contained in:
Yuji Sugiura 2024-05-24 15:09:05 +09:00 committed by GitHub
parent ed54eca119
commit b6e2d623d8
No known key found for this signature in database
GPG key ID: B5690EEEBB952194
3 changed files with 289 additions and 0 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

2
crates/oxc_linter/src/rules.rs
View file

@ -383,6 +383,7 @@ mod jsdoc {
pub mod require_property_name;
pub mod require_property_type;
pub mod require_returns;
pub mod require_returns_description;
pub mod require_yields;
}
@ -736,6 +737,7 @@ oxc_macros::declare_all_lint_rules! {
jsdoc::require_property_name,
jsdoc::require_property_description,
jsdoc::require_returns,
jsdoc::require_returns_description,
jsdoc::require_yields,
tree_shaking::no_side_effects_in_initialization,
}

257
crates/oxc_linter/src/rules/jsdoc/require_returns_description.rs Normal file
View file

@ -0,0 +1,257 @@
use oxc_diagnostics::OxcDiagnostic;
use oxc_macros::declare_oxc_lint;
use oxc_span::Span;
use crate::{
ast_util::is_function_node,
context::LintContext,
rule::Rule,
utils::{get_function_nearest_jsdoc_node, should_ignore_as_internal, should_ignore_as_private},
AstNode,
};
fn missing_description_diagnostic(span0: Span) -> OxcDiagnostic {
OxcDiagnostic::warn(
"eslint-plugin-jsdoc(require-returns-description): Missing JSDoc `@returns` description.",
)
.with_help("Add description comment to `@returns` tag.")
.with_labels([span0.into()])
}
#[derive(Debug, Default, Clone)]
pub struct RequireReturnsDescription;
declare_oxc_lint!(
/// ### What it does
/// Requires that the `@returns` tag has a description value.
/// The error will not be reported if the return value is `void `or `undefined` or if it is `Promise<void>` or `Promise<undefined>`.
///
/// ### Why is this bad?
/// A `@returns` tag should have a description value.
///
/// ### Example
/// ```javascript
/// // Passing
/// /** @returns Foo. */
/// function quux (foo) {}
///
/// // Failing
/// /** @returns */
/// function quux (foo) {}
/// ```
RequireReturnsDescription,
pedantic,
);
impl Rule for RequireReturnsDescription {
fn run<'a>(&self, node: &AstNode<'a>, ctx: &LintContext<'a>) {
if !is_function_node(node) {
return;
}
// If no JSDoc is found, skip
let Some(jsdocs) = get_function_nearest_jsdoc_node(node, ctx)
.and_then(|node| ctx.jsdoc().get_all_by_node(node))
else {
return;
};
let settings = &ctx.settings().jsdoc;
let resolved_returns_tag_name = settings.resolve_tag_name("returns");
for jsdoc in jsdocs
.iter()
.filter(|jsdoc| !should_ignore_as_internal(jsdoc, settings))
.filter(|jsdoc| !should_ignore_as_private(jsdoc, settings))
{
for tag in jsdoc.tags() {
if tag.kind.parsed() != resolved_returns_tag_name {
continue;
}
let (type_part, comment_part) = tag.type_comment();
// If returns type is marked as nothing, skip
if let Some(type_part) = type_part {
if matches!(
type_part.parsed(),
"void" | "undefined" | "Promise<void>" | "Promise<undefined>"
) {
continue;
}
}
// If description exists, skip
if !comment_part.parsed().is_empty() {
continue;
}
ctx.diagnostic(missing_description_diagnostic(tag.kind.span));
}
}
}
}
#[test]
fn test() {
use crate::tester::Tester;
let pass = vec![
(
"
/**
*
*/
function quux () {
}
",
None,
None,
),
(
"
/**
* @returns Foo.
*/
function quux () {
}
",
None,
None,
),
(
"
/**
* @returns Foo.
*/
function quux () {
}
",
Some(serde_json::json!([
{
"contexts": [
"any",
],
},
])),
None,
),
(
"
/**
* @returns {undefined}
*/
function quux () {
}
",
None,
None,
),
(
"
/**
* @returns {void}
*/
function quux () {
}
",
None,
None,
),
(
"
/**
* @returns {Promise<void>}
*/
function quux () {
}
",
None,
None,
),
(
"
/**
* @returns {Promise<undefined>}
*/
function quux () {
}
",
None,
None,
),
(
"
/**
* @function
* @returns
*/
",
None,
None,
),
(
"
/**
* @callback
* @returns
*/
",
None,
None,
),
];
let fail = vec![
(
"
/**
* @returns
*/
function quux (foo) {
}
",
None,
None,
),
(
"
/**
* @returns {string}
*/
function quux (foo) {
}
",
None,
None,
),
(
"
/**
* @return
*/
function quux (foo) {
}
",
None,
Some(serde_json::json!({ "settings": {
"jsdoc": {
"tagNamePreference": {
"returns": "return",
},
},
} })),
),
];
Tester::new(RequireReturnsDescription::NAME, pass, fail).test_and_snapshot();
}

30
crates/oxc_linter/src/snapshots/require_returns_description.snap Normal file
View file

@ -0,0 +1,30 @@
---
source: crates/oxc_linter/src/tester.rs
expression: require_returns_description
---
⚠ eslint-plugin-jsdoc(require-returns-description): Missing JSDoc `@returns` description.
╭─[require_returns_description.tsx:3:17]
2 │ /**
3 │ * @returns
· ────────
4 │ */
╰────
help: Add description comment to `@returns` tag.
⚠ eslint-plugin-jsdoc(require-returns-description): Missing JSDoc `@returns` description.
╭─[require_returns_description.tsx:3:17]
2 │ /**
3 │ * @returns {string}
· ────────
4 │ */
╰────
help: Add description comment to `@returns` tag.
⚠ eslint-plugin-jsdoc(require-returns-description): Missing JSDoc `@returns` description.
╭─[require_returns_description.tsx:3:17]
2 │ /**
3 │ * @return
· ───────
4 │ */
╰────
help: Add description comment to `@returns` tag.