doc: markdown links do not turn into real links

[jhamhader]

Hey,

I noticed that in various docs, links are not shown and actual markdown appears instead.

Examples:

• In tls.html:
  tlsSocket is the [tls.TLSSocket][] that the error originated from.
• In net.html:
  The parameter backlog behaves the same as in [server.listen(port, \[host\], \[backlog\], \[callback\])][].
• In cluster.html:
  When no more connections exist, see [server.close()][], the IPC channel to the worker will close allowing it to die gracefully.
• In crypto.html:
  Use [crypto.getCurves()][] to obtain a list of available curve names.

[estliberitas]

In crypto.html: Use [crypto.getCurves()][] to obtain a list of available curve names.

Already fixed but not landed yet by #5230.

[estliberitas]

Also here: https://nodejs.org/docs/latest-v5.x/api/errors.html: [EvalError][] ... [RangeError][] ... [URIError][]

Update: will fix in separate PR. It's about doc tool
Another update: this is not about doc tool, I was wrong, but actually this would be good to fix with doc tool (using types parser) by adding

• EvalError
• RangeError
• ReferenceError
• SyntaxError
• TypeError
• URIError

to global types list, so we can write just {SyntaxError} and all.

Actually, I'm wondering why not make type parser produce such links with <code></code>...

[estliberitas]

Also here: https://nodejs.org/docs/latest/api/console.html#console_console_dir_obj_options

Wondering if latest docs are not updated OR doc tool does not parse such links correctly.

Update: just checked with latest master locally, all is OK

[estliberitas]

• In net.html: The parameter backlog behaves the same as in [server.listen(port, [host], [backlog], [callback])][].

After debugging of marked package I found that it does not support links with ] character even if it's escaped. Regular expression responsible for parsing link definitions would not allow such case. The problem is in reference resolving part: \[([^\]]+)\]:. This means it will not parse things like [foo(\[bar\])].

Any thoughts on this? I can resolve this simply in a PR by removing [ and ] from link titles. But it would break meaning of those signatures a bit.

/cc @mscdex @thefourtheye guys I did not know who to ask, so asking you...

[thefourtheye]

cc @nodejs/documentation

[estliberitas]

@thefourtheye thx, now I know who to /cc 😉

[evanlucas]

ah, just saw this. The net issues should be fixed by #5358

[estliberitas]

tls and cluster links should be fixed by #5364.

[evanlucas]

Closing as all of the listed broken links have been fixed. Thanks for reporting!

[jhamhader]

@evanlucas Problem still exists in:

• Crypto
• Error
• HTTP

[evanlucas]

@jhamhader do you have links to them? I must be missing something. I'm not seeing them

[Knighton910]

@jhamhader could you link them here, because like @evanlucas mentioned, i just looked at the the issues and Pull Reqs pertaining to this issue and didn't spot anything. after you link them, well be sure to handle them.

[jhamhader]

• HTTP:
  • agent.createConnection(options[, callback])
  • http.request(options[, callback]) (createConnection parameter details)
• Errors: Errors (see EvalError, RangeError, URIError)
• Crypto: crypto.createCipher(algorithm, password) (missing bracket for Buffer in the password argument details)

[stevemao]

I confirm @jhamhader is correct.
Please reopen this.
PR income :)