Skip to content

docs: finish the remaining 5.x/4.x API reference consistency items - #2489

Open
bilashcse wants to merge 8 commits into
expressjs:mainfrom
bilashcse:fix/api-docs-style-consistency
Open

docs: finish the remaining 5.x/4.x API reference consistency items#2489
bilashcse wants to merge 8 commits into
expressjs:mainfrom
bilashcse:fix/api-docs-style-consistency

Conversation

@bilashcse

Copy link
Copy Markdown

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:

  1. Result comments in code samples use double quotes in many places (// => "text/html") while the
    rest of the site, and the Prettier singleQuote setting, use single quotes.
  2. The res.type() sample had a typo — res.type('png'); // => image/png: — with the value unquoted
    and a stray trailing colon (the typo 5.x docs are missing some documentation added in late 4.x versions #1881 links to).
  3. req.host and req.hostname were sorted differently: 5.x lists req.host first (alphabetical,
    like every other section), 4.x lists req.hostname first.
  4. The 5.x page description frontmatter said "The request object …" / "The response object …" while
    4.x and the opening sentence of both pages say "The req object …" / "The res object …".

Fix

  • Normalised 33 result comments across the 4.x and 5.x application/request/response pages to single
    quotes. Double quotes are kept where the sample legitimately shows JSON (// => callback({ "user": "tobi" }))
    or a raw HTTP header (// Host: "example.com:3000").
  • Fixed the res.type('png') sample to res.type('png'); // => 'image/png'.
  • Moved the 4.x req.host section above req.hostname so both versions are alphabetical. I picked
    the 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.
  • Aligned the 5.x request/response description frontmatter with 4.x and with the first sentence of
    each 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 existing npm run test:unit step of
the lint job. It walks every .mdx file under src/content/api/4x and src/content/api/5x and
asserts that:

  • no result comment quotes a plain string value with double quotes;
  • no result comment ends with stray punctuation (this is what would have caught the image/png: typo);
  • req.host is documented before req.hostname in both versions;
  • the request/response description frontmatter starts with "The req object represents" /
    "The res object represents".

Each assertion fails on main before this change and passes after it.

Docs

Added a "Style Conventions" subsection to docs/content.md under API Reference describing the
three 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.

…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>
@bilashcse
bilashcse requested a review from a team as a code owner August 12, 2026 06:10
@netlify

netlify Bot commented Aug 12, 2026

Copy link
Copy Markdown

Deploy Preview for expressjscom-preview ready!

Name Link
🔨 Latest commit 57f1c8b
🔍 Latest deploy log https://app.netlify.com/projects/expressjscom-preview/deploys/6a7c0e596a37560008df8679
😎 Deploy Preview https://deploy-preview-2489--expressjscom-preview.netlify.app
📱 Preview on mobile
Toggle QR Code...

QR Code

Use your smartphone camera to open QR code link.
Lighthouse
Lighthouse
1 paths audited
Performance: 95 (🔴 down 2 from production)
Accessibility: 100 (no change from production)
Best Practices: 100 (no change from production)
SEO: 100 (no change from production)
PWA: 80 (no change from production)
View the detailed breakdown and full score reports
🤖 Make changes Run an agent on this branch

To edit notification comments on pull requests, go to your Netlify project configuration.

@bilashcse

Copy link
Copy Markdown
Author

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 res.type('png') typo, and the 5.x request/response description frontmatter switching to "The req object ..." / "The res object ...").

Where we differ is req.host / req.hostname. #2487 makes 5.x match 4.x: it renames the 5.x req.host section to req.hostname, drops the example.com:3000 and [::1]:3000 samples, and reports 'example.com'. That would undo a real Express 5 behaviour change, since in 5.x req.host keeps the port and req.hostname is the one that strips it. This PR instead keeps both 5.x sections as they are and moves the 4.x req.host section above req.hostname, so the ordering is alphabetical in both versions without touching what either property is documented to return.

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant