[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Opaque objects and Emacs documentation

From: Dmitry Gutov
Subject: Re: Opaque objects and Emacs documentation
Date: Fri, 24 Jul 2020 03:43:41 +0300
User-agent: Mozilla/5.0 (X11; Linux x86_64; rv:68.0) Gecko/20100101 Thunderbird/68.10.0

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?

*help* buffer for project-root docs also shows 3 method implementations,
all of which are undocumented: documenting these methods would be more

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

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

reply via email to

[Prev in Thread] Current Thread [Next in Thread]