Re: Opaque objects and Emacs documentation

[Andy Moreton <andrewjmoreton@gmail.com>]

On Fri 24 Jul 2020, Dmitry Gutov wrote:

> On 24.07.2020 02:24, Andy Moreton wrote:
>
>> 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.
>
> IME, "ordinary users" don't read the manual. At least, not as the first stop.
> But sure, we'll need to add some more to it.

Indeed. The index in the manual needs improving so that "i project RET" finds
the "Working with Projects" node.

>> 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 ?
>
> Doesn't the Commentary cover most (all?) of the above?

The manual does cover most of this. User facing docs need to focus on
what the backends can do more than the project.el machinery, so as more
backends are added, some of the project.el descripion should probably
migrate to the elisp manual (as it is of more interest to developers).

> BTW, did you read the latest version of it in master?

Yes - belatedly, as I only found the info node after posting my previous
message.

>> The
>> *help* buffer for project-root docs also shows 3 method implementations,
>> all of which are undocumented: documenting these methods would be more
>> helpful.
>
> Fair point.
>
> But would those docs say anything more than
>
>   Return the root directory of a "transient" project
>
>   Return the root directory of a "vcs-backed" project

A one-liner to give a sense of what they do is fine: that is still more
helpful than a list of entries that all say "undocumented".

>> 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.
>
> I think Commentary covers the above now. Again, the latest version.

I read project.el from top of tree before posting: it was not clear what
the minimal set of methods that are required, nor what are the
constraints on how the implementations should behave.

>> 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.
>
> You might want to try pressing 'C-x p C-h'.

A useful entry point, but only once you know it exists! Making things
discoverable is important for getting new users up to speed.

    AndyM