Node: Missing documentation for tls.parseCertString

[chrisbroome]

• Version: all as of v8.1.4
• Platform: all
• Subsystem: all

There is currently no documentation for tls.parseCertString

Since this function exported, I'd consider it part of the public API and therefore it should probably have some documentation explaining what it does.

[bnoordhuis]

That function was exposed by accident more than anything else in commit af80e7b from 2013. It's probably better to move it to lib/internal than promote it to official API.

cc @indutny

[chrisbroome]

@bnoordhuis Makes sense to me.

Also, after looking it what it actually does, it's also almost identical to calling

querystring.parse(str, '\n', '=')

with the one exception being when the string is invalid:

querystring.parse('invalidCertString', '\n', '=')
// yields {invalidCertString: ''} instead of {}

[XadillaX]

If we move it to internal, I think it's a semver major.

[sam-github]

@chrisbroome did you call this API? for what purpose? It parses a format that doesn't appear to ever be produced by a public API, I don't see how it could be useful.

Calling it semver-major is safe, lets not doc, and move to internal for 9.x

[chrisbroome]

I never actually used the API in production code. Basically I was playing around in the REPL exploring what was available in the tls module. I just typed tls.<tab>, saw parseCertString, and wanted to know what its purpose was (I thought maybe it was a function that let you extract information from base64-encoded .pem files). Anyway, I went to the documentation, but the function wasn't there, so I decided to open the issue.

[sam-github]

OK. I don't personally think we should document something only to remove it in the next major. If we do document it, it should be doc-deprecated at least.

[XadillaX]

@sam-github I agree to remove it in the next major and document it now for deprecated.

[bnoordhuis]

I'd do the following:

1. Don't document it.
2. Move it to lib/internal and leave a stub function in lib/tls.js that prints a deprecation warning.
3. In the next major or the one after that, remove the stub.

[XadillaX]

@bnoordhuis I've created another PR #14218 to move the function to internal.

[bnoordhuis]

Closing, #14249 was merged last year.