[Top][All Lists]

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

Re: master 1e3b0f2: Improve doc strings of project.el

From: Eli Zaretskii
Subject: Re: master 1e3b0f2: Improve doc strings of project.el
Date: Fri, 19 Jun 2020 15:44:10 +0300

> Cc: emacs-devel@gnu.org
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Fri, 19 Jun 2020 15:30:33 +0300
> On 19.06.2020 14:24, Eli Zaretskii wrote:
>  > Feel free to suggest a correction.
> My suggested correction would be the previous wording. It might have 
> been more vague, but it covered both cases.

That'd be a step backwards, IMO.  I changed the doc string because in
its original form it didn't tell me enough to understand which buffers
could and couldn't be selected by that command.

In general, it is IMO wrong to make a doc string too vague because
there's some difficulty in saying something accurately and yet
succinctly enough.  We should look for solutions that don't leave our
doc strings too vague.

> > "Buffer in a current project"
> > sounds too vague at best to me: a project doesn't include any buffers.
> It includes their default-directory-es. Any idea how to modify the 
> docstring that the first sentence still fits on one line?

What kind of buffers are those, in normal use?  IOW, what buffers are
relevant to the project, but don't visit any file/directory?

Armed with that knowledge, I could suggest a more accurate doc string
that still tells enough to understand what the command does.


reply via email to

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