angular / angular/components

bug(date-adapter): Misleading JSDoc for createDate returns type

Open Beginner friendly
#33,059 2 comments 0 reactions 0 assignees View on GitHub
area: material/core gemini-triaged P3
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.