feat(jsii): check that referenced @param's exist#431
Conversation
| /** | ||
| * Register documentations on a ``spec.Documentable`` entry. | ||
| * | ||
| * @param sym the symbol holding the JSDoc information |
There was a problem hiding this comment.
It is sad that you're dropping rich documentation and making it less nice, while you're fixing the problems with it...
There was a problem hiding this comment.
Didn't feel like it was adding a lot of value. If the parameter is declared as sym: Symbol and the documentation basically says "this is the symbol", then I don't feel like the documentation is adding a lot of information.
Similarly for the return value. Declaration says: function(...): Docs, I don't feel the need to add @returns the docs.
| const actualNames = new Set((method.parameters || []).map(p => p.name)); | ||
| for (const param of params) { | ||
| if (!actualNames.has(param)) { | ||
| this._diagnostic(methodSym.valueDeclaration, ts.DiagnosticCategory.Error, |
There was a problem hiding this comment.
Could this be a warning instead? I mean - is there any reason to actually fail on this?
There was a problem hiding this comment.
It could, but I'm wary. In my experience, warnings don't get fixed. But sure, I'll throw in a warning.
There was a problem hiding this comment.
We can turn this into an error in a later version if you like (using. warning first gives some notice period, which is great for CDK releases :D)
There was a problem hiding this comment.
And - feel free to record this in an issue so we don't forget!
2 participants
Verify integrity of the documentation by forcing the parameter names
referred to in @param declarations to actually exist.
Fixes #422.
By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.