feat: add deprecation handling for parameters and methods in API documentation

src/components/patterns/Signature/Param.astro

@@ -40,9 +40,11 @@ interface Props {
   optional?: boolean;
   /** Version the parameter was added in, e.g. `"v4.20.0"`. */
   since?: string;
+  /** Version the parameter was deprecated in, e.g. `"v4.11.0"`. */
+  deprecated?: string;
 }
 
-const { name, type, default: defaultValue, optional = false, since } = Astro.props;
+const { name, type, default: defaultValue, optional = false, since, deprecated } = Astro.props;
 
 const hasProperties = Astro.slots.has('properties');
 
@@ -57,7 +59,7 @@ const displayType = optional && type ? `${type} | undefined` : type;
 
   <div class="param__body">
     {
-      (displayType || defaultValue !== undefined || since) && (
+      (displayType || defaultValue !== undefined || since || deprecated) && (
         <div class="param__meta">
           {displayType && (
             <span class="param__meta-item">
@@ -77,6 +79,12 @@ const displayType = optional && type ? `${type} | undefined` : type;
               <code class="param__value">{since}</code>
             </span>
           )}
+          {deprecated && (
+            <span class="param__meta-item param__meta-item--deprecated">
+              <span class="param__label">Deprecated in:</span>
+              <code class="param__value">{deprecated}</code>
+            </span>
+          )}
         </div>
       )
     }

src/components/patterns/Signature/Signature.astro

@@ -17,6 +17,8 @@
  * </Signature>
  *
  * <Signature type="Boolean" since="v4.5.0" />
+ *
+ * <Signature returns="Response" since="v4.2.0" deprecated="v4.11.0" />
  */
 import './Signature.css';
 
@@ -27,16 +29,18 @@ interface Props {
   type?: string;
   /** Version the member was added in, e.g. `"v4.16.0"`. */
   since?: string;
+  /** Version the member was deprecated in, e.g. `"v4.11.0"`. */
+  deprecated?: string;
   /** Heading text for the arguments section. */
   attributesTitle?: string;
 }
 
-const { returns, type, since, attributesTitle = 'Arguments' } = Astro.props;
+const { returns, type, since, deprecated, attributesTitle = 'Arguments' } = Astro.props;
 
 const hasReturnsSlot = Astro.slots.has('returns');
 const hasReturns = hasReturnsSlot || Boolean(returns);
 const hasAttributes = Astro.slots.has('attributes');
-const hasFooter = Boolean(type) || hasReturns || Boolean(since);
+const hasFooter = Boolean(type) || hasReturns || Boolean(since) || Boolean(deprecated);
 ---
 
 <section class="signature">
@@ -75,6 +79,12 @@ const hasFooter = Boolean(type) || hasReturns || Boolean(since);
             <code class="type-tag">{since}</code>
           </p>
         )}
+        {deprecated && (
+          <p class="signature__line signature__line--deprecated">
+            <span class="signature__line-label">Deprecated in:</span>
+            <code class="type-tag type-tag--deprecated">{deprecated}</code>
+          </p>
+        )}
       </div>
     )
   }

src/components/patterns/Signature/Signature.css

@@ -58,6 +58,16 @@
     font-weight: var(--font-weight-medium);
   }
 
+  .type-tag--deprecated {
+    border-color: var(--color-border-error);
+    background-color: var(--color-bg-error);
+    color: var(--color-text-error);
+  }
+
+  .signature__line--deprecated .signature__line-label {
+    color: var(--color-text-error);
+  }
+
   .signature__params {
     display: grid;
     grid-template-columns: minmax(8rem, 14rem) minmax(0, 1fr);
@@ -148,6 +158,11 @@
     color: var(--color-text-primary);
   }
 
+  .param__meta-item--deprecated .param__label,
+  .param__meta-item--deprecated .param__value {
+    color: var(--color-text-error);
+  }
+
   .param__desc {
     color: var(--color-text-secondary);
 

src/content/api/4x/api/application/index.mdx

@@ -6,6 +6,7 @@ description: Learn about the properties of the Express application object.
 import Alert from '@components/primitives/Alert/Alert.astro';
 import Signature from '@components/patterns/Signature/Signature.astro';
 import Param from '@components/patterns/Signature/Param.astro';
+import PackageManagerCommand from '@components/patterns/PackageManagerCommand/PackageManagerCommand.astro';
 
 The `app` object conventionally denotes the Express application.
 Create it by calling the top-level `express()` function exported by the Express module:
@@ -293,6 +294,29 @@ app.delete('/', function (req, res) {
 });
 ```
 
+### app.del()
+
+<Signature deprecated="v4.2.0">
+  <Fragment slot="attributes">
+    <Param name="path" type="String | RegExp | Array">
+      The path for which the middleware function is invoked; same as [app.delete()](#appdelete).
+    </Param>
+    <Param name="callback" type="Function | Function[]">
+      Callback functions; same as [app.delete()](#appdelete).
+    </Param>
+  </Fragment>
+</Signature>
+
+<Alert type="alert">
+
+`app.del()` is the alias of [`app.delete()`](#appdelete), originally introduced because `delete` was a reserved word in older JavaScript engines. It has emitted a deprecation warning since Express v4.2.0. Use `app.delete()` instead.
+
+You can update your code automatically with the following codemod:
+
+<PackageManagerCommand command="npx codemod@latest @expressjs/route-del-to-delete" />
+
+</Alert>
+
 ### app.disable()
 
 <Signature returns="Application">
@@ -817,7 +841,7 @@ although this matches
 and this matches too
 ```
 
-<Alert type="warning">
+<Alert type="alert">
 
 The following section describes `app.param(callback)`, which is deprecated as of v4.11.0.
 

src/content/api/4x/api/request/index.mdx

@@ -6,6 +6,7 @@ description: The req object represents the HTTP request and has properties for t
 import Alert from '@components/primitives/Alert/Alert.astro';
 import Signature from '@components/patterns/Signature/Signature.astro';
 import Param from '@components/patterns/Signature/Param.astro';
+import PackageManagerCommand from '@components/patterns/PackageManagerCommand/PackageManagerCommand.astro';
 
 The `req` object represents the HTTP request and has properties for the
 request query string, parameters, body, HTTP headers, and so on. In this documentation and by convention,
@@ -220,6 +221,22 @@ console.dir(req.hostname);
 // => 'example.com'
 ```
 
+### req.host
+
+<Signature type="String" deprecated="v4.5.0" />
+
+<Alert type="alert">
+
+`req.host` is a deprecated alias of [`req.hostname`](#reqhostname) and returns the same value — the hostname with the port number stripped off. It has emitted a deprecation warning since Express v4.5.0. Use `req.hostname` instead.
+
+</Alert>
+
+```js
+// Host: "example.com:3000"
+console.dir(req.host);
+// => 'example.com'
+```
+
 ### req.ip
 
 <Signature type="String" />
@@ -601,6 +618,26 @@ req.acceptsCharsets('us-ascii');
 
 For more information, or if you have issues or concerns, see [accepts](https://github.com/expressjs/accepts).
 
+### req.acceptsCharset()
+
+<Signature returns="String | false" deprecated="v4.5.0">
+  <Fragment slot="attributes">
+    <Param name="charset" type="String | String[]">
+      One or more character sets to test against the request's `Accept-Charset` header.
+    </Param>
+  </Fragment>
+</Signature>
+
+<Alert type="alert">
+
+`req.acceptsCharset()` is the singular alias of [`req.acceptsCharsets()`](#reqacceptscharsets) and behaves identically. It has emitted a deprecation warning since Express v4.5.0. Use `req.acceptsCharsets()` instead.
+
+You can update your code automatically with the following codemod:
+
+<PackageManagerCommand command="npx codemod@latest @expressjs/pluralize-method-names" />
+
+</Alert>
+
 ### req.acceptsEncodings()
 
 <Signature returns="String | false">
@@ -626,6 +663,26 @@ req.acceptsEncodings('br');
 
 For more information, or if you have issues or concerns, see [accepts](https://github.com/expressjs/accepts).
 
+### req.acceptsEncoding()
+
+<Signature returns="String | false" deprecated="v4.5.0">
+  <Fragment slot="attributes">
+    <Param name="encoding" type="String | String[]">
+      One or more encodings to test against the request's `Accept-Encoding` header.
+    </Param>
+  </Fragment>
+</Signature>
+
+<Alert type="alert">
+
+`req.acceptsEncoding()` is the singular alias of [`req.acceptsEncodings()`](#reqacceptsencodings) and behaves identically. It has emitted a deprecation warning since Express v4.5.0. Use `req.acceptsEncodings()` instead.
+
+You can update your code automatically with the following codemod:
+
+<PackageManagerCommand command="npx codemod@latest @expressjs/pluralize-method-names" />
+
+</Alert>
+
 ### req.acceptsLanguages()
 
 <Signature returns="String | String[] | false">
@@ -656,6 +713,27 @@ req.acceptsLanguages();
 
 For more information, or if you have issues or concerns, see [accepts](https://github.com/expressjs/accepts).
 
+### req.acceptsLanguage()
+
+<Signature returns="String | String[] | false" deprecated="v4.5.0">
+  <Fragment slot="attributes">
+    <Param name="lang" type="String | String[]" optional>
+      One or more languages to test against the request's `Accept-Language` header. If omitted, all
+      accepted languages are returned as an array.
+    </Param>
+  </Fragment>
+</Signature>
+
+<Alert type="alert">
+
+`req.acceptsLanguage()` is the singular alias of [`req.acceptsLanguages()`](#reqacceptslanguages) and behaves identically. It has emitted a deprecation warning since Express v4.5.0. Use `req.acceptsLanguages()` instead.
+
+You can update your code automatically with the following codemod:
+
+<PackageManagerCommand command="npx codemod@latest @expressjs/pluralize-method-names" />
+
+</Alert>
+
 Express (4.x) source: [request.js line 179](https://github.com/expressjs/express/blob/4.x/lib/request.js#L179)
 
 Accepts (1.3) source: [index.js line 195](https://github.com/jshttp/accepts/blob/f69c19e459bd501e59fb0b1a40b7471bb578113a/index.js#L195)
@@ -752,7 +830,7 @@ For more information, or if you have issues or concerns, see [type-is](https://g
   </Fragment>
 </Signature>
 
-<Alert type="warning">
+<Alert type="alert">
 
 Deprecated. Use either `req.params`, `req.body` or `req.query`, as applicable.