Repository navigation
doc: undocumented entities in code example in repl.md #12686
Description
Activity
The last two should probably be documented.
@vsemozhetbyt If this hasn't been addressed yet I can take that responsibility.
Do you think the
close()method and thebufferedCommandproperty should be added to theREPLServerclass description or adding comments to code snippets is enough ?Reacted by Vse Mozhe Buty@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.
@cjihrig I am curious why
REPLServer.bufferedCommandshould 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 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. :)
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.
- added a commit that references this issue
on Aug 1, 2017
Currently, we have 3 undocumented entities in code example in
repl.md:replServer.lineParser.reset()replServer.bufferedCommandreplServer.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()?