createPushResponse() callback needs better documentation

[arei]

• Version: 10.8.0
• Platform: docs
• Subsystem: http2

http2: documentation for createPushResponse() in Http2ServerResponse should spell out what its callback returns more clearly. My interpretation was that it would return similar to ServerHttp2Stream.pushResponse() but it does not. In specific, headers are not passed to the callback of createPushResponse().

node/lib/internal/http2/compat.js

Line 670 in fc84666

callback(null, new Http2ServerResponse(stream));

[arei]

It's also in the wrong place in the documentation, alphabetically speaking.

[ghost]

@arei ：

Thanks for your suggestions first!

It's also in the wrong place in the documentation, alphabetically speaking.

What about fixing like this following?

#### response.createPushResponse(headers, callback)
<!-- YAML
added: v8.4.0
-->
* `headers` {HTTP/2 Headers Object} An object describing the headers
* `callback` {Function}

Call [`http2stream.pushStream()`][] with the given headers, and wraps the
given [`Http2Stream`] on a newly created `Http2ServerResponse` as the callback
parameter when callback is successful. And for the closed stream, The callback
will be called with an error `ERR_HTTP2_INVALID_STREAM`.

Feel free to tell me if there's something wrong or should be also fixed :)

[ghost]

/cc：@vsemozhetbyt, @mcollina, @Trott

[arei]

I think it would be better to explicitly state the signature of the callback function, e.g. callback(err,stream)or even better like the callback is written in for http2stream.pushStream().

[ghost]

#### response.createPushResponse(headers, callback)
<!-- YAML
added: v8.4.0
-->
* `headers` {HTTP/2 Headers Object} An object describing the headers
* `callback` {Function} Callback that is called once `[`http2stream.pushStream()`][] ` has finished, or
  when the stream is closed.
  * `err` {Error}
  * `stream` {ServerHttp2Stream} The newly-created `ServerHttp2Stream` object.

Call [`http2stream.pushStream()`][] with the given headers, and wraps the
given [`Http2Stream`] on a newly created `Http2ServerResponse` as the callback
parameter when callback is successful. And for the closed stream, The callback
will be called with an error `ERR_HTTP2_INVALID_STREAM`.

[ghost]

@arei：

Yes, I've prepared to describe this in details in two parts:

1. Simple introductions of the callback :including each of the callback parameters.
2. Details info: What will happen for a successful callback and what's with that when failed.

[ghost]

Waiting for others' suggestions from this submit :)

[Trott]

@nodejs/http2 @nodejs/documentation

[jasnell]

This was resolved

[ericrannaud]

This documentation change is incorrect. The prototype given for the callback states in the itemized list that the second argument is:
stream {ServerHttp2Stream} The newly-created ServerHttp2Stream object

But the code does, on successful creation of the stream:

node/lib/internal/http2/compat.js

Line 798 in 21f2e88

callback(null, new Http2ServerResponse(stream));

So the second argument of the callback is a Http2ServerResponse, not the underlying ServerHttp2Stream. The doc correctly states this in the rest of the text.