doc: improve https module documentation

[mscdex]

Checklist

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

Affected core subsystem(s)

• doc

Description of change

This commit makes the following changes:

• Reduces redundancy
• Highlights class inheritance
• Adds function descriptions
• Uses consistent language and formatting in text and consistent coding style in examples

[mscdex]

/cc @nodejs/documentation @nodejs/collaborators

[indutny]

I think it is requestListener in http docs, why change it here?

[mscdex]

(Eventual) Consistency? I am working on it all one module at a time.

[indutny]

So is it going to be changed in http.md after this PR?

[mscdex]

Yes, that is my plan. I'm actually working on http.md right now.

[indutny]

Sorry then! LGTM

[indutny]

One nit, otherwise LGTM.

[thefourtheye]

There should be some explanation for this implements. Inherits and implements is kinda confusing.

[mscdex]

I'm open to suggestions on naming, formatting, etc. The goal here is to document inheritance and the like, which also helps reduce redundant documentation.

I just thought of something that would be neat, but is out of the scope of what I'm trying to do at the moment: if we could (dynamically) integrate collapsed (by default) sections that would show inherited events, methods, and properties (one collapsed section per type). That would help prevent having to navigate to a separate page to see inherited API while still leaving the UI less cluttered and easy to see API unique to that object.

[jasnell]

I've been considering this also but it's going to be a bit difficult given how we currently manage the documentation. I've been thinking about a more radical approach where we break the documentation up a bit more in order to make individual APIs easier to document and modify. I think, for now, however, this is a good change as is.

[mcollina]

I'm 👎 on reducing redundancy. I've found out that a lot of developers have a rough understanding of how TLS works, how self-signed certificate works, how to set them up and the like.
In https://github.com/mqttjs/MQTT.js#mqttclientstreambuilder-options we are linking to tls.connect(), and we are getting a huge number of questions related to those options, and how to use them. I like the fact that all the options for 'tls' are in 'https' as well.

Still, this PR is great from a maintenance point of view or if you know how TLS works. Most people do not want to get into TLS plumbing, the just want a quick primer on how to use the 'https' module.

[mscdex]

@mcollina I don't understand the problem when we have a link to both http.request() and tls.connect() together there in the description. Are you saying most users can't be bothered to click another link?

[mcollina]

@mscdex I have seen people struggling to grasp both http and tls at the same, and they have to retain multiple conceptual layers which is currently unnecessary. It's about cognitive context switching.

The current docs serve both as a reference and as a way to learn a topic. Removing the duplication will retain the function as a reference, but will damper the function as learning manual.

[mscdex]

Well, I'm open to finding other ways to reduce physical redundancy. If there is some clever way to pull in the list of options from tls.connect() on-the-fly or something, then that's fine too I guess. IMHO the duplicating of documentation can lead to inconsistencies. I am already seeing instances of this while reviewing the documentation for various modules.

[jasnell]

While the current documentation is a bit limited and can be confusing, I think the key will be in making incremental steps towards improving rather than making significant sweeping changes all at once. These changes LGTM with a couple of nits.

[mcollina]

@mscdex can you please add a link on what a self-signed certificate is and how to set that up? Something related to rejectUnauthorized and DEPTH_ZERO_SELF_SIGNED_CERT.

[jasnell]

Ping @mscdex ... what do you want to do with this?

[mscdex]

I'm still interested in landing it, I just haven't had time yet to dive back into the docs again.

[yorkie]

small nit: Agent should be in lowercase?

[jasnell]

Closing due to lack of any forward progress on this. @mscdex ... please reopen if you wish to keep pursuing it.