Re: Opaque objects and Emacs documentation

[Dmitry Gutov]

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.

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

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

> 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

?

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

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

It's a good quick overview, even if you'll have to guess at the 
semantics of "current project".