A comment opening a function body is documentation in the wrong place. It explains the function it sits inside, but it sits one line below the declaration where a reader, an editor tooltip and every call site would look for it. Moving it up costs nothing and reaches everyone.
This is the companion to tsdoc-on-declaration, which asks for the explanation on the declaration, and to no-comment-run, which stops it from sprawling once it is there. Together they close the loop: the explanation cannot sit below the declaration, and it cannot grow into narration.
The report names the fix, which depends on what the function is:
a named function or method has a declaration, so the comment becomes its TSDoc;
a callback has none, so the body is lifted into a named, documented function that is passed instead. This is sharpest in a watcher, where a body that needs explaining is a body that wants a name;
a test has a title, which is what a failure prints, so the comment folds into it.
Four things are not reported.
Directives, which are aimed at the code rather than describing it, by the same prefixes no-comment-run recognises.
A TSDoc block over a declaration, which documents that declaration rather than the function holding it. Only a /** block earns this: a plain /* */ or a // above the same declaration is prose about the enclosing function until it is rewritten as TSDoc, which is what the report asks for.
A comment that is the whole body of an intentionally empty function, which is the one place it belongs.
Test containers and lifecycle hooks. A comment introducing an it() describes that test, and belongs to the title rather than to the describe arrow that happens to hold it. A beforeEach has neither a declaration to document nor a title to fold into, and its body is setup that reads no better as a named function, so the rule would have no fix to offer. Playwright namespaces both under test, and test.beforeEach and test.describe are exempt exactly as the bare forms are, while test.skip and it.each stay tests: a property is read as the kind only when it names one.
The rule is deliberately not autofixable. Prose written for the inside of a body is rarely the sentence that belongs on the declaration, and a mechanical move would produce a TSDoc summary that describes one branch rather than the function.
@rotki/no-leading-body-comment
📖 Rule Details
A comment opening a function body is documentation in the wrong place. It explains the function it sits inside, but it sits one line below the declaration where a reader, an editor tooltip and every call site would look for it. Moving it up costs nothing and reaches everyone.
This is the companion to
tsdoc-on-declaration, which asks for the explanation on the declaration, and tono-comment-run, which stops it from sprawling once it is there. Together they close the loop: the explanation cannot sit below the declaration, and it cannot grow into narration.The report names the fix, which depends on what the function is:
Four things are not reported.
Directives, which are aimed at the code rather than describing it, by the same prefixes
no-comment-runrecognises.A TSDoc block over a declaration, which documents that declaration rather than the function holding it. Only a
/**block earns this: a plain/* */or a//above the same declaration is prose about the enclosing function until it is rewritten as TSDoc, which is what the report asks for.A comment that is the whole body of an intentionally empty function, which is the one place it belongs.
Test containers and lifecycle hooks. A comment introducing an
it()describes that test, and belongs to the title rather than to thedescribearrow that happens to hold it. AbeforeEachhas neither a declaration to document nor a title to fold into, and its body is setup that reads no better as a named function, so the rule would have no fix to offer. Playwright namespaces both undertest, andtest.beforeEachandtest.describeare exempt exactly as the bare forms are, whiletest.skipandit.eachstay tests: a property is read as the kind only when it names one.The rule is deliberately not autofixable. Prose written for the inside of a body is rarely the sentence that belongs on the declaration, and a mechanical move would produce a TSDoc summary that describes one branch rather than the function.
⚙️ Options
Nothing.
🚀 Version
This rule was introduced in
@rotki/eslint-pluginv1.7.0🔍 Implementation