doc: fix invalid path doc comments

[Trott]

Affected core subsystem(s)

doc, path

Description of change

The format of certain code comments in the path documentation results
in the code blocks being invalid. I also find it confusing at least as
formatted on the website. This change is intended to improve those
comments.

[evanlucas]

I think the goal was to get syntax highlighting for what was returned. I find it more readable the way that it currently is...

[Trott]

/cc @nodejs/documentation

[benjamingr]

LGTM although I'm +0 on this, not sure this makes things better.

[phillipj]

I would go for consistency throughout the docs over personal preference here. ATM it seems we mix two styles:

In buffer.markdown and http.markdown

// returns: true

In path.markdown and querystring.markdown

// returns
true

I'm +1 on landing this if we do the same change for querystring - might be a separate PR of course. Otherwise buffer and http should be changed.

And multiline results should be commented with // rather than /* .. */ as the former is used for documenting multiline console output in most cases.

[jasnell]

LGTM

[mscdex]

LGTM

[Trott]

And multiline results should be commented with // rather than /* .. */ as the former is used for documenting multiline console output in most cases.

Rebased, made that change, force pushed.

[jasnell]

Still LGTM

[Trott]

There are some LGTM's but also at least one (mild?) preference for the current formatting. I see no strong objections. I'll land this in 24 hours or so unless either a collaborator indicates they'd strongly prefer this not land, or unless there is a significant pile-up of milder objections from collaborators (let's say two more people).

[Trott]

Landed in 9eb0ef4

[MylesBorins]

@Trott this is going to need some manual backporting love

[Trott]

@thealphanerd Sure: #5797