[Tutor] Do you use doctests to show API use even when you normally use unit tests?

[Cameron Simpson]

On 04May2020 08:44, DL Neil <PyTutor at danceswithmice.info> wrote:
[...snip...]
>However, one of the irritating, almost arrogant, features of many 
>F/LOSS projects (not specifically Python then) is the way some authors 
>insist that the way to learn about their grand-creation, is to read the 
>code (cf RTFM!). This is true, and doubly-so for security reasons, 
>but... it is also a high 'barrier to entry'. Many a project would 
>receive better take-up if it explained its API, at least with How-to 
>examples. Initial application would be a lot faster (and 
>motivational!), per @Alan's comment. [...]

I also find this irritating, but for other reasons.

Reading the code is indeed a great way to learn how something was 
implemented, and in principle to learn what assumptions the author may 
have made which are not clarified in the documentation, and/or what 
bugs/limitations the implementation may have which are no elucidated in 
the documentation. _If_ the code is accessable, meaning here "readable".

However, it is a LOUSY way to learn about the problem that is being 
solved, and about the _semantics_ which are purported to be supplied.  
Here I mean that the code will tell you what happens. But only the docs 
will tell you which implementation specific aspects of the code are to 
be relied upon by the user of the code.

A typical trite example is interning strings of the same value or ints 
of the same value, or interning re regexp object with the same pattern 
definition.  In Python, these are CPython implementation details (eg 
happens for small ints, and I think the re module guarentees a limited 
size cache), but someone reading the code might presume that this is 
guarenteed, and therefore that "s1 is s2" is a fast way to compare 
strings for equality. (Which, IIRC, in PHP _is_ guarenteed.)

Any number of more complex examples abound, such as presuming some 
internal data structure (and therefore specific performance 
characteristics or features).

I trip over devs all the time who confuse the implementation with the 
specification. And I hate it.

Most recent example was a dev who asserted that anyone would read 
something's docstring out of the source file versus say, help(). Bah! I 
for one have things which augument the raw source docstring. help() 
and/or the generated docs are the reference.

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