[docs] Add an example to the Base.prompt docstring

[DilumAluthge]

No description provided.

[logankilpatrick]

@DilumAluthge why does prompt need to be prefixed with base?

[DilumAluthge]

prompt is not exported from Base, so you can't use it by just doing prompt; you need to do Base.prompt.

[logankilpatrick]

I do not think we should export it

Can you add some context as to why? Just for my own understanding :)

[DilumAluthge]

It just seems like a very short generic word that doesn't necessarily need to be exported. Plus Base.prompt isn't really too long to type.

I don't feel particular strongly though, so if other people really want to export prompt, I won't object.

[logankilpatrick]

My only argument is to have parity with Python (where you would use input) but not sure if that is compelling for other people or not.

[DilumAluthge]

If, in the future, we do end up exporting prompt from Base, we would edit this example to change Base.prompt( to prompt(.

[IanButterworth]

Perhaps also add Base.prompt to the docs in this PR too?

[IanButterworth]

Oh I didn't see #43637

[DilumAluthge]

Perhaps also add Base.prompt to the docs in this PR too?

#43637

I should explain my rationale for keeping this PR and #43637 separate. This PR (adding an example to the docstring) doesn't need a lot of discussion (and can be merged pretty quickly) because it doesn't change any guarantees about the public API.

In contrast, #43637 makes Base.prompt part of the public API, so I would want other people to chime in and confirm that they agree with the decision to make it part of the public API. So that PR will need more discussion (and maybe a quick run by triage) and will probably be open for a longer period of time.