Re: Opaque objects and Emacs documentation

[Yuan Fu]

> On Jul 17, 2020, at 3:22 PM, Dmitry Gutov <dgutov@yandex.ru> wrote:
> 
> On 17.07.2020 17:26, Gregory Heytings via Emacs development discussions. 
> wrote:
>> Of course I did.  But as it happens, this difference does not exist in 
>> Emacs.  Remember that one of the direct inspirations of Emacs were Lisp 
>> machines, in which the user can read and modify almost every piece of code 
>> on the fly, from the lowest to the highest level.  In such a system, there 
>> can be no difference between "internal" and "external" documentation.
> 
> Why not?
> 
> Given that Lisp allows one to expect any value, and jump to any 
> implementation, and debug any function, I would say that actually _lowers_ 
> the need to document things, in general, not the other way around, like in 
> environments which you can't inspect and thus have to rely solely on 
> documentation.

For the return value, I think documenting the return value is better than not 
doing so. Sure, I can evaluate the function and see the return value, but 
reading off the documentation is much easier. Why make other people’s life 
harder?

For documentation in general, I think the right thing to do is to document the 
function, clearly state that this is “internal” and shouldn’t be depended upon, 
and explain the reason why (or just say “see doctoring of xxx for why”). I 
don’t see why saying nothing is better than being explicit in documentation.

> 
> As for internal vs external difference, I believe it's still here, as with 
> any programming language. The latter should be much shorter. There is no need 
> to dump all internal details on somebody who just wants to use a library. 
> It's simply counter-productive.
> 

As it happens to Emacs (and other free software), users often _are_ developers. 
Library authors should document their code to make it as easy as possible for 
others to look at the code and understand what it does, and start hacking on 
it. IOW, one writes documentation not merely for users, but for his fellow 
developers. (I guess this doesn’t apply to personal projects, but Emacs is as 
collaborative as it gets, so the point should still hold.)

Yuan