doc: Improve doc for Http2 headers object

[Flarna]

Add more details regarding processing and data type of incoming headers in Http2.

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[Trott]

@nodejs/documentation

[apapirovski]

I'm not convinced most of this belongs in the http2 documentation since we're just following the spec (and it applies to http too). I am potentially in favour of documenting the type of the :status header.

[Flarna]

@apapirovski My start point in this was the :status header as I was surprised that it is no string. By looking closer into the code and http docs I found subtle differences therefore I thought it's better to write down all details - similar as in http (see https://nodejs.org/dist/latest/docs/api/http.html#http_message_headers).
I found following differences:

• The list of headers where duplicates is discarded differs between http and http2 implementation
• set-cookie is always an array for http, in http2 only if there are more values

I'm fine with removing some of the details, replace it by references to http or http2 spec (or even code).
Or maybe these differences are actually bugs?

[vsemozhetbyt]

Maybe a colon after `cookie`?

[Flarna]

done

[Flarna]

I was thinking once more regarding the difference in handling of set-cookie between http2 and http. This effects also the http2 compat API so it is not that compatible as it could be.

Till now this diff is not documented and http2 is experimental so this gap could be closed easily.

@nodejs/http2 any opinion in this?

[Flarna]

@apapirovski What do think about following: Duplicates where only a single value is allowed (e.g. content-type, age,...) are discarded.?
Still clarifies that duplicates are discarded but without the burden to keep doc and code in sync.

[apapirovski]

@Flarna I would be fine with that but this has approvals as is so don't feel pressured to make the change. I think I'm in the minority in my opinion :)

[Flarna]

@apapirovski I took a fast look into the history and it seems the headerlist is unchanged since ~9 month. Therefore I think it's ok to mention all headers in doc as the risk of getting out of sync is low.

[vsemozhetbyt]

Let's land this, say, tomorrow if there are no strong objections?

[apapirovski]

Landed in 8132413