Re: Opaque objects and Emacs documentation

[Andy Moreton <andrewjmoreton@gmail.com>]

On Fri 17 Jul 2020, Stefan Monnier wrote:

>> Basically, you are saying that in your opinion this is as it should
>> be, and cannot be helped.
>>
>> Which I think is against long-time Emacs tradition for documenting its
>> interfaces, and by that facilitating extensibility.  It is IMO wrong
>> to fill Emacs application levels with opaque objects which cannot be
>> usefully described; they should be a rare exception, but definitely
>> not the rule.
>
> I believe in this specific case, the issue is that the shape can and
> will change and not only over time.  The only thing defined is an
> interface and any code which relies on more than this interface
> (e.g. a function which relies on completion-tables being lists of
> strings) will break sooner or later.
>
> Of course, that doesn't prevent the doc from giving *examples* to show
> the intended behavior.

I have read this (rather long) thread, and its discussion of all kinds
of low level detail, but it seems the bigger picture is missing.

Documentation is needed for three distinct audiences:
a) Emacs users
b) Developers adding new methods to provide a new project implementation
   which conform to the project API (genric functions)
c) Developers extending the project.el infrastructure.
   This is already covered by the commentry in the code (I hope).

Taking the first two cases in turn:

a) Users:
Currently there is no documentation that I can see in the manuals for
the project feature for users. As an ordinary user, it is not clear what
problem project.el solves, or how it helps users with their work.

So, please try to extend the docs and the manual for users to state:
 - what is a project ?
 - what is the "current project" ?
 - what is the "transient project" (mentioned in project-current) ?
 - why is this useful ? How does it help the user ?
 - what is the interface for users ?
 - how do users discover this interface ?

The doc string for project-root uses the term "current project" without
defining it. What is the "current project" ? How is it chosen ? The
*help* buffer for project-root docs also shows 3 method implementations,
all of which are undocumented: documenting these methods would be more
helpful.


b) Project backend developers
The commentary at the top of project.el describes the project interface
fairly loosely. The docs need to describe the interface more precisely:
 - which functions must be implemented ?
 - which functions are optional ?
 - what should a developer consider when choosing which optional
   functions to implement ?
 - what is important to consider when implementing these functions ?
 - if return values are opaque types consumed by other functions, then
   the docs must clearly state which interface functions consume this
   data.

There has been lengthy discussion about documenting the data types used
in the project interface for each implementation. If the interface
behaviour is precisely specified, the exact data types are perhaps less
important. However it can still be helpful to describe the data types
for developers learning how the pieces fit together, even if it is not
part of the API contract.

                                -=o0o=-

As an ordinary user, project.el requires significant investment of time
and effort to discover if it might be useful or not. Most users do not
read the elisp sources, and are not necessarily familiar with CL generics.

Documenting project.el so that learning process is as short as possible
would be a great service to emacs users.

    AndyM