/cc @nodejs/documentation

Ping @mcrummey: Any chance you can update this in accordance with the comments from @sam-github?

Updated the PR to include @sam-github comments. Thanks for your patience and please let me know there are any other issues.

@sam-github @nodejs/documentation Is this an OK way to show the output of the sample code? If so, anyone want to approve this change? If not, anyone want to suggest a better way to do it to @mcrummey?

Looks like the standard way in our docs to show example code output.

I still feel the example offers no value. The only thing it shows that the docs don't is what the address family string can be for IPv4, and for that purpose, it is incomplete, because what about IPv6?

Does anybody object to deleting the example?

Does anybody object to deleting the example?

I guess I wouldn't object, but I also feel like sample code is inherently valuable.

Even a one line example that shows a console.log of an object? What is the value?

Even a one line example that shows a console.log of an object? What is the value?

Since you seem to feel it should be removed, and I could go either way on it, let's remove it (unless someone else has a different opinion).

Added IPv4|IPv6 and removed example.

Landed in 109bfd2.
Thanks for the contribution @mcrummey! 🎉

An aside: We could use greater standardization for these elements of an API. For example, which of the below is preferred?

• rinfo {Object} - Remote address information
• rinfo {Object} Remote address information
• rinfo {Object}. Remote address information
• rinfo {Object}, Remote address information
• rinfo {Object} remote address information
• rinfo {Object} Remote address information.

...and so on. It seems like there's a lot of permutations in the docs.

@nodejs/documentation

I like

• rinfo {Object} - Remote address information

personally, I think dashes are normally used for giving more info about something.

Sounds like we should have a How to write docs guide to go with the How to write tests one. Then we could have all our bikeshedding in that, and define a standard style to use everywhere in the docs.

I think the current method of "it looks like this is the style that was used two lines up, so let's stick with that" is a little haphazard.

Heh, I dislike dashes there, but will accept nearly anything if it means we will have a single consistent style. :-D

I think I'd prefer no punctuation, especially given how the docs render on the website:

That dash looks out of place to me, like a mistake.

If there must be punctuation, a colon makes more sense to me than a dash. It also has the added benefit of eliminating the hyphen vs. en dash vs. em dash decision/confusion.

But... if everyone loves a dash/hyphen/whatever there, then I'll get on board! No problem! :-D

I agree it looks a bit weird on the website, I was looking at the Github markdown formatting:

which I think works quite well. I agree the dash looks too short on the website, and that we don't really want to get in to the en/em dash differences. I think on the website you're right, no punctuation will work next to that big green <Object>, so I'd go for that.

EDIT: To clarify, I think it's more important that it looks good on the website, as that's where most people will be looking at it. So +1 for nothing.

Ah, I see, yeah, the dash looks just fine on GitHub itself.
¯\(ツ)/¯

Can someone confirm that these changes apply to v6 and v4?

@MylesBorins I confirm that they apply back to v4 (and probably much farther).