bug(date-adapter): Misleading JSDoc for createDate returns type
- Dominant language
- TypeScript
- Stars
- 25k
- Forks
- 6.8k
- Avg merge
- 1d 8h
- Merged PRs (30d)
- 91
Description
### Is this a regression?
- [ ] Yes, this behavior used to work in the previous version
### The previous version in which this bug was not present was
_No response_
### Description
(I don't know if it sould be a bug or docs-bug, because it's about JSDoc that not available in the material doc
website, so I couldn't join a link to the doc and create a docs-bug issue).
In the JSDoc of the DateAdapter createDate method, the returns tag indicates that :
@returns The new date, or null if invalid.
But the method returns type is just D, not D | null so it can't be null.
And in the different implementations of the date adapter, when the params are invalid, an error is throws, not a null return.
### Reproduction
This bug is more a docs-bug, but date-adapter JSDoc is not directly available from the doc website, so I couldn't join a link to create a docs-bug.
The components/src/material/core/datetime/date-adapter.ts, line 110
### Expected Behavior
the returns tag indicates that an error is throws when invalid
### Actual Behavior
the returns tag indicates that null is returned when invalid
### Environment
no specific env
Contributor guide
Research direction
Start at components/src/material/core/datetime/date-adapter.ts around line 110 and inspect the createDate method's JSDoc alongside its declared return type. Confirm the documented invalid-input behavior against the method description and implementations mentioned in the issue. Done means the JSDoc accurately describes the return type and what happens when the input is invalid.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- angular, typescript
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 1/5
- Estimated time
- Under an hour
- Activity status
- Quiet
- Clarity
- Clearly specified
- Newbie friendliness
- 78/100