Re: master 1e3b0f2: Improve doc strings of project.el

[Dmitry Gutov]

On 17.07.2020 18:27, tomas@tuxteam.de wrote:
> I was rather trying to highlight the contrast between (a) the library
> designer(s) set the interface design and (b) the interface evolves
> as a collective effort of designers and users.

An interface's ability to evolve over time isn't entirely predicated on 
there being no limitations on its use. It can easily change as a result 
of user feedback anyway.

> Reality will be a mix
> of both, of course. The term API conveys a hierarchy -- clearly in
> camp (a).
>
> The "system programmer" thing comes from former times, yes.

BTW, lower level programming is not devoid of abstractions as well. I 
could be wrong in some details here, but a file descriptor seems like a 
prime example of an abstraction.

The docs say it's represented by a number, but it's not a "real" number 
(you never do any arithmetic with it), and an fd can be backed by very 
different mediums: a file on disk, a network socket, a pipe, etc. And 
everything is a number in C anyway. It's an "opaque" value.

When using it in a piece of code, you don't always have to know what 
kind of file it is. Or you just know it's a socket, for instance. But 
you know there are certain things one can do with a file descriptor, 
like passing it to 'write' or 'read'.