Document Format enum members in @typespec/json-schema - #11540
Document Format enum members in @typespec/json-schema#11540timotheeguerin wants to merge 1 commit into
Conversation
microsoft-github-policy-service
Bot
added
meta:website
531e126 to
642ad15
Compare
There was a problem hiding this comment.
Pull request overview
Improves the published reference docs for @typespec/json-schema by adding meaningful documentation for Format enum members and fixing a doc-comment parsing issue around @extension.
Changes:
- Added per-member documentation for the
Formatenum (and surfaced it in the website reference docs). - Fixed
Jsondoc text so@extensionisn’t parsed as a doc tag by escaping it with backticks. - Added a Chronus entry for the documentation update.
Reviewed changes
Copilot reviewed 3 out of 3 changed files in this pull request and generated 2 comments.
| File | Description |
|---|---|
| website/src/content/docs/docs/emitters/json-schema/reference/data-types.md | Updates the published reference docs for Json and Format, including descriptions and links. |
| packages/json-schema/lib/main.tsp | Adds doc comments to Format members and fixes/parses Json documentation content and property description. |
| .chronus/changes/docs-json-schema-2026-8-11.md | Adds a changelog entry for the documentation change. |
| /** A time of day, as defined by the `full-time` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). */ | ||
| time: "time", | ||
|
|
||
| /** A duration, as defined by the `duration` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#appendix-A). */ |
| | dateTime | `"date-time"` | A date and time, as defined by the `date-time` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). | | ||
| | date | `"date"` | A calendar date, as defined by the `full-date` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). | | ||
| | time | `"time"` | A time of day, as defined by the `full-time` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#section-5.6). | | ||
| | duration | `"duration"` | A duration, as defined by the `duration` production in [RFC 3339](https://datatracker.ietf.org/doc/html/rfc3339#appendix-A). | |
|
You can try these changes here
|
642ad15 to
ff07fe6
Compare
|
Updated in ff07fe6 — but partly pushing back on the premise. RFC 3339 does define a That said, the readability concern is fair: readers associate RFC 3339 with timestamps, so an unqualified link is misleading. Reworded to name ISO 8601 explicitly while keeping the normative reference:
Regenerating the docs applied the same change to |
commit: |
|
All changed packages have been documented.
Show changes
|
2e20080 to
31c2091
Compare
The 18 members of
Formatare the values users pick from when applying@format, and every one of them renders with an empty description in the reference docs. Each now says what it means and links the RFC that defines it.Also fixes a doc comment on
Jsonthat the doc parser silently truncates:* as opposed to a schema. Use in combination with the @extension decorator. For example,@extensionis read as a doc tag, so everything after it is swallowed as tag content and never reaches the published page. Backticks fix it.Prerequisite for #1229 and #2090. The library linter rule that catches this is in #11543, which must merge after this one:
lint-typespec-libraryruns with--warn-as-errorinside every package'sbuild, so the docs have to exist before the rule is turned on.Independent of the other documentation PRs (#11539, #11541, #11542) — they touch disjoint packages and can merge in any order.