angular / angular/components

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

Offen Anfängerfreundlich
#33,059 2 Kommentare 0 Reaktionen 0 zugewiesene Personen Auf GitHub ansehen
area: material/core gemini-triaged P3
Vorherrschende Sprache
TypeScript
Sterne
25k
Forks
6.8k
Ø Merge
1 T. 8 Std.
Gemergte PRs (30 T.)
91

Beschreibung

### 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

Beitragsleitfaden

Beitragsleitfaden öffnen

Rechercherichtung

Beginne bei components/src/material/core/datetime/date-adapter.ts ungefähr in Zeile 110 und prüfe den JSDoc-Kommentar der createDate-Methode zusammen mit ihrem deklarierten Rückgabetyp. Gleiche das dokumentierte Verhalten bei ungültigen Eingaben mit der Methodenbeschreibung und den im Issue erwähnten Implementierungen ab. Erledigt ist die Aufgabe, wenn der JSDoc-Kommentar den Rückgabetyp und das Verhalten bei ungültigen Eingaben korrekt beschreibt.

Vom Indexierungsmodell aus dem Issue-Text verfasst.

Bewertung

Tech-Stack
angular, typescript
Bereich
documentation
Issue-Typ
Dokumentation
Schwierigkeit
1/5
Geschätzter Aufwand
Unter einer Stunde
Aktivitätsstatus
Ruhig
Klarheit
Klar beschrieben
Anfängerfreundlichkeit
78/100

Neue Issues direkt in Ihr Postfach

Eine kurze Übersicht über anfängerfreundliche GitHub-Issues.