Comments (7)
- If param comments are missing, api-extractor catches them and throws an error.
This might be a little overly strict. Consider this example:
/** Represents a 2D vector. */
public class Vector {
/** The first component of the vector */
public x: number;
/** The second component of the vector */
public y: number;
/**
* Constructs a new instance of the `Vector` class
* @param x - the first component of the vector
* @param y - the second component of the vector
*/
public constructor(x: number, y: number) {
}
}
Would we really want to insist that the person write this @param
documentation for the constructor? I recall that the old MSDN was fairly dogmatic about this, however this documentation clearly doesn't convey any useful information. Although I'm personally a big advocate of documentation, I tend to be wary of practices that encourage people to think of commenting as an empty formalism or "going through the motions." When we author docs, we should always be thinking about the audience, what questions they will have, and how our content will help them.
- If params are out of order, also worthy of throwing an error.
Hmm... I hadn't thought of that one. Tools like API Extractor could normalize this automatically when they generate the .d.ts files, but yeah, I can see the value of doing this in the source code.
- If the params have types in them, api-extractor ignores them and parses the types from typescript typings if available.
- If the params have dashes in them, api-extractor ignores the dashes. If they are missing dashes, api-extractor ignores that. (The purpose is to extract the docs and api surface, not be nit picky about unimportant things, especially when VSCode jsdoc formatting defaults to having types AND no dashes.)
Agreed. My motivation for being strict about parsing @param
tags was to protect against mistakes. But you have a fair point that the documentation tool itself already needs to match the parameter name against the function arguments, so for example if @param This is not fine
incorrectly interprets "This" as a parameter name, it will still get caught during matching.
I'll point out that today the @microsoft/tsdoc library only looks at comments -- it has no idea what the function parameters are, or even whether the comment is for a class or function etc. When the dust settles on API Extractor 7, I'd like to consider whether it would be useful to provide some context to @microsoft/tsdoc so that we can move some of this validation down into the library. We might get better error messages that way.
See Airbnb specs for their guidance as an example.
Hrmmm... the example you linked to doesn't use @param
at all. It might not be the best example of a modern style guide any more: 😋
// good
/**
* make() returns a new element
* based on the passed-in tag name
*/
function make(tag) {
// ...
return element;
}
from tsdoc.
Oops on the link; edited above and replaced with a jsdoc one that's more applicable.
This might be a little overly strict.
I should have worded that better; i was thinking more about "if you provide comments for one param, you should provide them for all". Or, if someone modifies a signature but the comments don't match (e.g. they're out of order, some are unrecognized or missing) then that could be caught. Totally agree we definitely don't want it to be frictiony by erroring on things that are not useful to correct. :)
from tsdoc.
This still seems to be an issue for @typeParam
, without the hyphen it fails to parse the parameter name for the tag.
from tsdoc.
I tagged it for follow up. If it's easy maybe I can tackle this in the next round of work on the parser.
from tsdoc.
Locally I wrote a patch for NodeParser.prototype._parseParamBlock
in JS to partially address this case:
var hyphenExcerpt;
var spacingAfterHyphenExcerpt;
if (tokenReader.peekTokenKind() === Token_1.TokenKind.Hyphen) {
tokenReader.readToken();
hyphenExcerpt = tokenReader.extractAccumulatedSequence();
// TODO: Only read one space
spacingAfterHyphenExcerpt = this._tryReadSpacingAndNewlines(tokenReader);
}
else if (tokenReader.peekTokenKind() !== Token_1.TokenKind.AsciiWord) {
tokenReader.backtrackToMarker(startMarker);
this._parserContext.log.addMessageForTokenSequence("tsdoc-param-tag-missing-hyphen" /* ParamTagMissingHyphen */, 'The @param block should be followed by a parameter name and then a hyphen', docBlockTag.getTokenSequence(), docBlockTag);
return new nodes_1.DocParamBlock({
configuration: this._configuration,
blockTag: docBlockTag,
parameterName: ''
});
}
Essentially, it allows @typeParam T this is a comment
(or @param p this is a comment
), but it doesn't yet permit @typeParam T {constraint} comment
(or @param p {type} comment
).
from tsdoc.
I formalized my patch above and added additional parsing support for {type}
and [name]
/[name=default]
syntax in a PR at #206.
from tsdoc.
This fix was published with TSDoc 0.12.18. Thanks @rbuckton for making the PR!
from tsdoc.
Related Issues (20)
- `eslint-plugin-tsdoc`: Check types referenced through `{@link}` and `{@inheritDoc}`
- Upgrade Node.js and `node-sass` dependencies HOT 1
- Validate invalid params through tsdoc eslint plugin HOT 1
- This repo is missing important files
- Documentation coverage? HOT 1
- JSDoc/TSDoc `@inherit[dD]oc` mismatch HOT 1
- Is it dead? HOT 4
- VS Code unable to load Schema
- tsdoc-unnecessary-backslash false positive
- Weird warnings about multiple declarations HOT 1
- Grouping classes under the same index name
- Support for defining custom tag syntax HOT 1
- tsdoc-html-tag-missing-equals erroneously flagging boolean attributes
- tsdoc-malformed-html-name erroneously flagging use of less than symbol HOT 1
- Unable to load schema from 'https://json.schemastore.org/tsconfig HOT 1
- `tsdoc-reference-unquoted-identifier` is incorrectly reported for certain identifiers
- [ Question ][ Playground ] Intended Behaviour? HOT 2
- eslint-plugin-tsdoc: Missing rule to check for absence of a TSDoc comment HOT 1
- ESLint flat configurations? HOT 1
- "extends": "@rushstack/heft-node-rig/profiles/default/config/jest.config.json"
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from tsdoc.