Baffled by readline module

[Cameron Simpson]

On 09Mar2023 13:08, Grant Edwards <grant.b.edwards at gmail.com> wrote:
>On 2023-03-09, Chris Angelico <rosuav at gmail.com> wrote:
>> Not sure about the history file, and I would assume that if you don't
>> configure one, history is simply lost when you restart. But with tab
>> completion, unless you need to be able to input a tab character, it
>> should be safe to ignore the feature and leave it at the defaults.
>
>Indeed, that seems to be how it works (though I never found that
>stated anywhere in the docs).
>
>What's really weird about the docs is that when it is described it
>doesn't even _mention_ that it provides command-line recall and
>editing:
[...]

I think this might be the common case of a module which wraps another 
library: there's a tension between describing everything in pointless 
detail and the trite "we're just shimming this library, go read its 
docs".

The module documentation needs to:
- not insult the reader by saying nearly nothing ("this is just GNU 
   readline, hooked to Python!") I'm looking at you, many "man" pages on 
   a GNU based system which say "oh just go and read GNI info, it's all 
   over there"
- be detailed enough to enumerate the API calls and at least summarise 
   their semantics
- be general enough to not overprescribe so that small shifts in the 
   library as it evolves don't cause falsehoods in the module docs (and a 
   nightmarish maintenance burden)

Similar example: the "os" modules, which largely shims the OS POSIX 
calls. It lists them and has a paragraph on their purpose and the 
meaning of the flags (for example). But the platform specifics and fine 
grained stuff is off in "man 2 foo" for the Python "os.foo" function.

[...]
>It finally dawned on me after seeing an example I found elsewhere that
>you don't call some module method to fetch the next user-entered line.
>
>You call the input() built-in.

Ah. That's not overtly stated? [...reads...] Ah, there it is in the last 
sentence of the opening paragraph. Not quite as in-your-face as I'd have 
liked it. That paragraph could do with being a bullet list of use cases.

Cheers,
Cameron Simpson <cs at cskk.id.au>