[readline doc] include line/cursor in readline documentation

[Js-Brecht]

Documents the existence and purpose of the line and cursor properties, in an effort to make their usage public.

line can be used for reading the current input value during runtime, if reading from a TTY stream. Both properties are necessary when developing a custom CLI input process using readline as an input processor. This allows you to utilize the work that's been done in readline, instead of trying to recreate it.

Refs: #30347
Refs: DefinitelyTyped/DefinitelyTyped#40513

Checklist

• documentation is changed or added
• commit message follows commit guidelines

[addaleax]

@nodejs/readline

[Js-Brecht]

@addaleax Is it normal for it to take this long to get a review? Not trying to rush you guys at all; I'm sure that you all have tremendous work loads. Just wondering so I know what to expect 🙂

[addaleax]

@Js-Brecht I mean, it depends, but pings are generally appreciated.

I’m not sure I can really review this because it’s not obvious to me whether this should be public, documented API or not; in any case, added: REPLACEME seems a bit odd because this being a docs-only PR usually means that the properties already exist and have been added in earlier releases?

[Js-Brecht]

@addaleax not sure who to ping here; I see you pinged the readline team already, so I suppose I can just wait for them.

in any case, added: REPLACEME seems a bit odd because this being a docs-only PR usually means that the properties already exist and have been added in earlier releases?

That was my initial instinct, as well, until I saw this portion of the contributing guide:

If you are adding to or deprecating an API, use REPLACEME for the version number in the documentation YAML.

I wasn't entirely sure if the practice was to use the version when the documentation was added, or when the property itself was added. Regardless, the standard syntax for the rest of the docs seem to include the YAML documentation, so I felt I would be remiss by not including it.

If the version number here refers to when the documentation was added, then REPLACEME seems appropriate. If not, do you think I should try to find the version where these particular properties were added, or simply exclude the YAML doc altogether?

I'd imagine the line property will have been around since the beginning of the Interface class (and most likely the cursor property, as well); perhaps v0.1.104? The version numbers for the members of that class do not seem to all seem to agree, which would make sense if those versions were later the class's. Case in point: several of the events were added in v0.1.98 (before the class itself?), including the line event. This is why the meaning/purpose of that version number, or that portion of the guide, is not entirely clear to me.

I could just go with the lowest common denominator, but before I did that, I would need to go digging to see if I can find the first appearance 🤔.

[addaleax]

If not, do you think I should try to find the version where these particular properties were added, or simply exclude the YAML doc altogether?

Yes, that would be the right thing here – it usually doesn’t matter because newly added documentation is also for newly added code :)

I'd imagine the line property will have been around since the beginning of the Interface class (and most likely the cursor property, as well); perhaps v0.1.104? The version numbers for the members of that class do not seem to all seem to agree, which would make sense if those versions were later the class's. Case in point: several of the events were added in v0.1.98 (before the class itself?), including the line event. This is why the meaning/purpose of that version number, or that portion of the guide, is not entirely clear to me.

It’s v0.1.98 here. The reason for the class itself being marked with v0.1.104 is that that was when the class export was added; i.e. readline.createInterface() is older than readline.Interface.

[addaleax]

Landed in bd9be04