From 51f90640816bb38c4392e94516118e142dec5f20 Mon Sep 17 00:00:00 2001
From: ChloeVPin <227690662+ChloeVPin@users.noreply.github.com>
Date: Wed, 1 Jul 2026 11:15:35 -0500
Subject: [PATCH] doc: clarify http2 compatibility API example

Replace the introductory compatibility API example that set the same
header twice with a straightforward writeHead() example. Add a short
note that setHeader() and writeHead() headers are merged, with
writeHead() taking precedence.

Refs: https://github.com/nodejs/node/issues/25952
Signed-off-by: ChloeVPin <227690662+ChloeVPin@users.noreply.github.com>
---
 doc/api/http2.md | 18 ++++++++++++------
 1 file changed, 12 insertions(+), 6 deletions(-)

diff --git a/doc/api/http2.md b/doc/api/http2.md
index 9e9c3f8d3f0232..e80d91ed633ca7 100644
--- a/doc/api/http2.md
+++ b/doc/api/http2.md
@@ -3966,9 +3966,10 @@ API:
 ```mjs
 import { createServer } from 'node:http2';
 const server = createServer((req, res) => {
-  res.setHeader('Content-Type', 'text/html');
-  res.setHeader('X-Foo', 'bar');
-  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+  res.writeHead(200, {
+    'Content-Type': 'text/plain; charset=utf-8',
+    'X-Foo': 'bar',
+  });
   res.end('ok');
 });
 ```
@@ -3976,13 +3977,18 @@ const server = createServer((req, res) => {
 ```cjs
 const http2 = require('node:http2');
 const server = http2.createServer((req, res) => {
-  res.setHeader('Content-Type', 'text/html');
-  res.setHeader('X-Foo', 'bar');
-  res.writeHead(200, { 'Content-Type': 'text/plain; charset=utf-8' });
+  res.writeHead(200, {
+    'Content-Type': 'text/plain; charset=utf-8',
+    'X-Foo': 'bar',
+  });
   res.end('ok');
 });
 ```
 
+When both [`response.setHeader()`][] and [`response.writeHead()`][] are used,
+headers are merged, with headers passed to [`response.writeHead()`][] taking
+precedence over headers set earlier with [`response.setHeader()`][].
+
 In order to create a mixed [HTTPS][] and HTTP/2 server, refer to the
 [ALPN negotiation][] section.
 Upgrading from non-tls HTTP/1 servers is not supported.