nodejs/node

http2 API documentation issues

Open

#25952 opened on Feb 5, 2019

View on GitHub
 (13 comments) (0 reactions) (0 assignees)JavaScript (117,218 stars) (35,535 forks)batch import
dochelp wantedhttp2

Description

Compatibility API example

Here's the example code from the API docs in the compatibility API section:

const http2 = require('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' });
  res.end('ok');
});

The Content-Type header is overwritten here in writeHead(), but unless the reader knows that writeHead() merges its headers with the headers set in setHeader(), the reader may think there's something special going on here.

Suggestion: remove first call to setHeader(); ensure example is straightforward

No documentation of HTTP2_HEADER_* constants

There are many references to e.g., http2.constants.HTTP2_HEADER_STATUS. These are not listed in the constants section. Is HTTP2_HEADER_CONTENT_TYPE different than 'Content-Type'? Can these be used interchangeably? If I use the compatibility API, should I use these constants?

Suggestion: document the constants and when to use them.

Contributor guide

Tech stack
nodejsjavascript
Domain
documentation
Issue type
documentation
DifficultyEstimated implementation difficulty for a new contributor, from 1 for very small changes to 5 for expert-level work.
3
Estimated timeA rough time range for an experienced contributor to investigate, implement, test, and prepare a pull request.
1-3 hours
Activity statusHow available the issue appears right now: fresh, active, stale, blocked, or waiting on maintainer input.
fresh
ClarityHow clearly the issue explains the expected change, acceptance criteria, and next step.
clear
Prerequisites
Basic understanding of Node.js HTTP2Familiarity with documentation markdown
Newbie friendlinessA 1-100 score estimating how approachable this issue is for first-time contributors.
70
Research direction
Review the HTTP2 documentation source file (likely 'doc/api/http2.md') in the Node.js repository. Examine the compatibility API example and the constants section. Look at the current state of http2 constants to understand the pattern used for other constants. Consider discussing with maintainers via comments on the issue to clarify the desired format for constants documentation.