New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
feat(check-values): @throws must not be empty #481
Conversation
including docs, tests
Please see my comment at #480 (comment) And I just noticed your comment there about this. :) |
Originally posted by @brettz9 in #480 (comment)
|
I don't understand what you're meaning with "checking types" and "require types on other tags"? (For now) I just want to check for empty values (instead of doing a full validation of
|
By "checking types", in the context of So rather than modifying the But As far as "require types on other tags", I mean being able to add a feature like this: 'jsdoc/valid-types': ['error', {tagsWithRequiredType: [
'throws', 'typedef'
]}] This would then report cases where there was an empty (Ideally, there'd be a |
And if you were curious, the reason we don't require all tags that accept types/namepaths to automatically have them is because of such as these reasons:
|
My latest thinking is for {
tags: {
// Replacement for `checkSeesForNamepaths: true`
see: {
// Name position expects a namepath if present (not just plain text)
name: 'namepath',
// Indicates that a name position is required (not just that if present, it is a namepath); can also
// include "type"; default is an empty array with neither required
required: ['name'],
// Explicitly disallows any bracketed type; default is `true` (to allow valid types within
// brackets). Note: `type` does not accept "text" as a value (as `name` does) since
// bracketed types are not free form in jsdoc whereas the name position can
// sometimes be free form (when not a namepath)
type: false
},
// The following should probably be applied by default if jsdoc expects at least something for `@throws`
throws: {
// If `name` is set to `type`, can be plain text in name position, e.g., `@throws This is an error`; i.e.,
// not needing to be a "namepath"; the default
name: 'text',
// Must have either type (e.g., `@throws {aType}`) or name (`@throws Some text`); this option is
// necessary as distinct from `name` and `type` since it indicates that one or the other is required
required: ['typeOrName']
}
}
} Besides allowing projects to enforce having some type or name in @golopot: Are you ok with this API? |
Am now thinking this should be as settings since we have |
…uredTags` setting to control whether the type and namepath portions should be checked for validity and whether such portions are required, and to let user-defined "namepath-defining" tags be added to defined types. Closes gajus#481 BREAKING CHANGE: Drops `checkSeesForNamepaths` setting. Use `{settings: {jsdoc: {structuredTags: {name: 'namepath', type: false, required: ['name'],}}}}` instead. Also: 1. Requires a name for `event` and `external` (and `extends` in jsdoc mode); some tweaking of other tags per docs 2. Clarifies in more cases where a problem is specific to the mode or not 3. Reports simulaneous invalid name *and* type errors 4. `typdef` now requires `allowEmptyNamepaths: false,` to report empty names (as with other tags)
…uredTags` setting to control whether the type and namepath portions should be checked for validity and whether such portions are required, and to let user-defined "namepath-defining" tags be added to defined types. Closes gajus#481 BREAKING CHANGE: Drops `checkSeesForNamepaths` setting. Use `{settings: {jsdoc: {structuredTags: {name: 'namepath', type: false, required: ['name'],}}}}` instead. Also: 1. Clarifies in more cases where a problem is specific to the mode or not 2. Reports simultaneous invalid name *and* type errors 3. `typdef` now requires `allowEmptyNamepaths: false,` to report empty names (as with other tags) 4. Requires a name for `event` and `external` (and `extends` in jsdoc mode); some tweaking of other tags per docs
…uredTags` setting to control whether the type and namepath portions should be checked for validity and whether such portions are required, and to let user-defined "namepath-defining" tags be added to defined types. Closes gajus#481 BREAKING CHANGE: Drops `checkSeesForNamepaths` setting. Use `{settings: {jsdoc: {structuredTags: {name: 'namepath', type: false, required: ['name'],}}}}` instead. Also: 1. Clarifies in more cases where a problem is specific to the mode or not 2. Reports simultaneous invalid name *and* type errors 3. `typdef` now requires `allowEmptyNamepaths: false,` to report empty names (as with other tags) 4. Requires a name for `event` and `external` (and `extends` in jsdoc mode); some tweaking of other tags per docs
…uredTags` setting to control whether the type and namepath portions should be checked for validity and whether such portions are required, and to let user-defined "namepath-defining" tags be added to defined types. Closes #481 BREAKING CHANGE: Drops `checkSeesForNamepaths` setting. Use `{settings: {jsdoc: {structuredTags: {name: 'namepath', type: false, required: ['name'],}}}}` instead. Also: 1. Clarifies in more cases where a problem is specific to the mode or not 2. Reports simultaneous invalid name *and* type errors 3. `typdef` now requires `allowEmptyNamepaths: false,` to report empty names (as with other tags) 4. Requires a name for `event` and `external` (and `extends` in jsdoc mode); some tweaking of other tags per docs
🎉 This issue has been resolved in version 30.0.0 🎉 The release is available on: Your semantic-release bot 📦🚀 |
@throws
requires a value, see https://jsdoc.app/tags-throws.htmlFor example, https://github.com/autoNumeric/autoNumeric/blob/next/src/AutoNumeric.js is incorrectly declaring
@throws
without values.