doc: undocumented entities in code example in repl.md

[vsemozhetbyt]

• Subsystem: doc, repl

Currently, we have 3 undocumented entities in code example in repl.md:

replServer.lineParser.reset()
replServer.bufferedCommand
replServer.close()

The first one will be gone since Node.js v8.0.0

The second one can be considered as an acceptable ad-hoc internal revelation.

Is it worth to document the third one, replServer.close()?

[cjihrig]

The last two should probably be documented.

[anchnk]

@vsemozhetbyt If this hasn't been addressed yet I can take that responsibility.

Do you think the close() method and the bufferedCommand property should be added to the REPLServer class description or adding comments to code snippets is enough ?

[vsemozhetbyt]

@anchnk I am not sure, sorry. cc @nodejs/documentation ?

If nobody else answers, feel free to open a PR with any decision and we may correct this later in the PR.

[lance]

@cjihrig I am curious why REPLServer.bufferedCommand should be documented. Is this one of those undocumented properties that people tend to depend on? If not, I'm curious if it really makes sense to start documenting it now. It really does feel like an implementation detail. Somewhat related, is an issue I opened last year which I (embarrassingly) have done nothing about yet. #7619

[cjihrig]

@lance that's just my opinion because it is a public property without an underscore. If it's going to stick around like that, it should probably be documented. Otherwise, we should move to deprecate/remove it.

[lance]

@cjihrig in my opinion, minimizing the public surface area is in the best long term interest, especially in cases like this where it does seem that the property is a leakage of the implementation. Making this property public and documented means that the implementation, or at least this part of it anyway, needs to remain in place in spite of potential needs/changes in the future.

I understand that removing something that's public, even if it's not documented, is generally frowned upon - or at least thought about pretty thoroughly. As you said, it's just my opinion. :)

[cjihrig]

I completely agree that less surface area is better. These things should have probably never been made public API. But they're still public, and get harder to remove all the time.

[lance]

In #7619 @jasnell suggests close() should be considered documented and left as-is since it's inherited from readline.Interface.

Now that lineParser is gone as of 8.x and REPLServer.bufferedCommand has been made private, I think this can be closed.