Re: Opaque objects and Emacs documentation

[Dmitry Gutov]

Hi Alan,

On 21.07.2020 22:36, Alan Mackenzie wrote:

> What precisely forces you
> to use such difficult and arcane facilities?  What does it gain you that
> you couldn't get out of plain Emacs Lisp (without things like
> cl-generic)?

Sorry, could you just read this thread? Or the description of the package.

As I said, the closest alternative would be using functions with 
OO-style dispatch arguments, akin to completion tables. I don't think 
you'd like that option better.

> > This is sorted out by each individual backend which knows how to access
> > fields inside "project instances" belonging to it, and which implements
> > the aforementioned protocol for that instance type.
>
> Trouble is, when I'm trying to debug a problem involving such code, that
> style of coding adds an order of magnitude onto the time and effort
> needed.

Sometimes, when we need more advanced capabilities for our programs, 
that can indeed result in less trivial debugging. The alternative would 
be not writing said program at all.

> if it is not documented in detail, it will add another order of magnitude
> onto the time to debug it; anybody needing to know the structure of a
> return value in detail, possibly to check it's valid, would first have to
> read and understand the intricate details of the source code, and
> effectively recreate in her private notes the details missing from the
> doc string.

You can only know it's valid by looking at the "Implementations:" list 
in 'M-x describe-function RET project-root RET'.

You won't know it is valid just by reading some examples of return values.

> That isn't fun.  Not so long ago I gave up on an Edebug bug because the
> proliferation of inadequately documented cl- functions in edebug.el just
> made it too tedious to continue.

Edebug is difficult. So far I have no idea why that is: perhaps because 
of the coding style, but more likely just due to the problem domain.

But we indeed have old code that is unnecessarily difficult. At some 
point, I had a lot of trouble following the code in etags.el. Lots of 
implicit state and dynamic variables everywhere.

Eli did some cleanups after that, but I'm yet to form an opinion on how 
much they changed things.

> > I am adamantly against this because it's against the design (clients
> > should program against the public interface, not against the
> > implementation), and is likely to encourage incorrect programs.
>
> That's known as "security by obscurity", I think.

No, abstraction and security are largely orthogonal.

> I think your fear is
> misfounded.  For a start, if the public interface is adequate, people
> will use it in preference to dissecting internal structures.

That means documenting the public interface adequately first. And for 
that, the description needs to be abstraction-oriented.

> When gaps
> are found in that interface, people will use the internal details to
> craft a workaround whether the documentation is there or not.  (I have
> done this at least once in the past.)

Either inadequate public interface, or inadequate documentation, or 
programmer laziness (or "cowboy-ism"). I wouldn't presume to say which 
was the cause more, but I've seen this in practice pertaining to the 
package under discussion.