docs: finish the remaining 5.x/4.x API reference consistency items - #2489
docs: finish the remaining 5.x/4.x API reference consistency items#2489bilashcse wants to merge 8 commits into
Conversation
…se docs Signed-off-by: Nazmul Hossain <bilashcse@gmail.com>
Signed-off-by: Nazmul Hossain <bilashcse@gmail.com>
Signed-off-by: Nazmul Hossain <bilashcse@gmail.com>
…request docs Signed-off-by: Nazmul Hossain <bilashcse@gmail.com>
Signed-off-by: Nazmul Hossain <bilashcse@gmail.com>
Signed-off-by: Nazmul Hossain <bilashcse@gmail.com>
Signed-off-by: Nazmul Hossain <bilashcse@gmail.com>
Signed-off-by: Nazmul Hossain <bilashcse@gmail.com>
✅ Deploy Preview for expressjscom-preview ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Heads up on overlap: #2487 is also open against #1881 and touches two of the same files. Where we agree, the changes are identical (the Where we differ is This PR also covers the first checkbox in #1881, which #2487 does not: 33 result comments across the 4.x and 5.x application/request/response pages move from double to single quotes, plus the unit test and the docs/content.md section. Happy to defer or rebase on whichever you would rather merge first. |

Closes the three remaining unchecked items in #1881.
Problem
The 4.x and 5.x API reference pages drifted apart after the redesign, which makes it hard to tell a
real API difference from a formatting difference when switching versions:
// => "text/html") while therest of the site, and the Prettier
singleQuotesetting, use single quotes.res.type()sample had a typo —res.type('png'); // => image/png:— with the value unquotedand a stray trailing colon (the typo 5.x docs are missing some documentation added in late 4.x versions #1881 links to).
req.hostandreq.hostnamewere sorted differently: 5.x listsreq.hostfirst (alphabetical,like every other section), 4.x lists
req.hostnamefirst.descriptionfrontmatter said "The request object …" / "The response object …" while4.x and the opening sentence of both pages say "The
reqobject …" / "Theresobject …".Fix
quotes. Double quotes are kept where the sample legitimately shows JSON (
// => callback({ "user": "tobi" }))or a raw HTTP header (
// Host: "example.com:3000").res.type('png')sample tores.type('png'); // => 'image/png'.req.hostsection abovereq.hostnameso both versions are alphabetical. I pickedthe 5.x order because every other section on the page is alphabetical — happy to flip it the other
way if you prefer the deprecated alias to stay last.
descriptionfrontmatter with 4.x and with the first sentence ofeach page.
No prose or behaviour was changed, only formatting, ordering and the one typo.
Tests
Added
tests/unit/api-docs-style.test.mjs, which runs in the existingnpm run test:unitstep ofthe
lintjob. It walks every.mdxfile undersrc/content/api/4xandsrc/content/api/5xandasserts that:
image/png:typo);req.hostis documented beforereq.hostnamein both versions;descriptionfrontmatter starts with "The req object represents" /"The res object represents".
Each assertion fails on
mainbefore this change and passes after it.Docs
Added a "Style Conventions" subsection to
docs/content.mdunder API Reference describing thethree conventions and pointing at the test that enforces them, so the next person editing these pages
knows the rules without having to diff 4.x against 5.x.