Re: Opaque objects and Emacs documentation

[Andy Moreton]

On Fri 24 Jul 2020, Andy Moreton wrote:

> 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.

Having sent this, I then found that there is a "Working with Projects"
section in the manual, but which is not easily found from the top level
and is not indexed so it can be found by looking for "project".

    AndyM