Node: Inconsistent documentation: hostname vs host

[apapirovski]

The Node.js documentation is currently rather freeform when it comes to distinguishing between hostname and host. There are arguments and properties named host that refer to hostname and their description makes as much clear. There are also arguments and properties that refer to host in both the name and the description, despite actually intending to represent the hostname.

This can without any doubt create confusion for end users but also for contributors. For a recent example see: https://github.com/nodejs/node/pull/20875 or https://github.com/nodejs/node/pull/20493

I think it would be nice if we could slowly update the the documentation and code to be more clear about this. While we cannot change property names on options objects, argument names can certainly be changed and documentation can be updated.

Some example entries:

https://nodejs.org/dist/latest-v10.x/docs/api/tls.html#tls_tls_checkserveridentity_host_cert
https://nodejs.org/dist/latest-v10.x/docs/api/tls.html#tls_tls_connect_port_host_options_callback
https://nodejs.org/dist/latest-v10.x/docs/api/tls.html#tls_tls_connect_options_callback
https://nodejs.org/dist/latest-v10.x/docs/api/net.html#net_server_listen_options_callback

[apapirovski]

@nodejs/documentation @nodejs/http @nodejs/http2

[mcollina]

Definitely 👍 . I think this would be a good source of tasks for a code&learn.

[styfle]

I agree, this is a source of confusion for myself.

This ASCII Chart does a good job of explaining the difference.

I even found a Chrome Bug after reading through the Node.js docs regarding hostname assignment.

All that to say, I agree with this change 👍

[davisokoth]

Interested in picking this up...

[apapirovski]

@davisokoth let me know if you need any guidance. There are a few links in the OP to documentation mistakes but it would be nice to also update some of the variable names in our code. Feel free to also open a PR just with one of those documentation changes — we don't have to change everything all at once.

[benjipelletier]

Also interested in contributing to this

[lliepert]

Also interested in contributing to this if help is still needed

[UlisesGascon]

I am also interested in contributing...

[thatshailesh]

@apapirovski anything left to be done or can you please point other issue to work on?

[sagirk]

I'm working on doc/api/net.md and the corresponding lib/net.js.

[graezzon]

I'm interested in getting involved in this project. Thanks guys.

[apapirovski]

@thatshailesh @sagirk @graezzon There's definitely more to be done. Some of the links in the OP haven't been updated and there are likely more instances of this in the codebase. Just look for any irregularities of hostname vs host usage, in particular cases where the term is used interchangeably to refer to the same thing.

[sagirk]

@apapirovski I ran a project-wide search and found a few instances of this issue in

• doc/api/tls.md and the corresponding lib/tls.js
• doc/api/net.md and the corresponding lib/net.js _(taken; I'm working on this)_
• doc/api/dns.md and the corresponding lib/dns.js

[sagirk]

@benjipelletier @lliepert @UlisesGascon @thatshailesh @graezzon Take a look at one of the files listed above and claim it in this thread so we know who is working on what.

[UlisesGascon]

Thanks @sagirk! I am working now in doc/api/dns.md and lib/dns.js. I can take tls too after that if nobody else does ;-)

[thatshailesh]

Hi All
I will be taking doc/api/tls.md and lib/tls.js
Thanks @sagirk

[yokanand]

Hi guys, I'm late to join. I'm interested to contribute as well. Can I get started. Are there any open tasks to pick up?