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

[Eli Zaretskii <eliz@gnu.org>]

> Cc: emacs-devel@gnu.org, "Philip K." <philip@warpmail.net>
> From: Dmitry Gutov <dgutov@yandex.ru>
> Date: Fri, 19 Jun 2020 15:54:56 +0300
> 
> > 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, those would be the buffers where (project-current) would 
> return the current project. I think that's pretty unambiguous.

That's the implementation, but it cannot be used to make the doc
string useful, at least not directly.  It tells you what is the test
for whether a particular buffer is eligible for the switch, but the
doc string should instead tell up front what are the general traits of
all the eligible buffers.  IOW, the user should understand which of
the buffers he or she can switch to with this command.

> >>> "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?
> 
> If you look at bug#41868, it mentions VC-Dir and Dired buffers. Perhaps 
> Philip also has other examples.

So will something like the below do the job?

    Switch to another buffer related to the current project.
  A buffer is related to a project if its `default-directory'
  is inside the directory hierarchy of the project's root.

Btw, AFAIU this command can prompt for a project's root, but the doc
string doesn't mention that important fact.

> It also cleans up some "invisible" buffers created to service the files 
> in the project, such as ones created by Flymake, etc.

By "it" what do you mean here? you don't mean
project-switch-to-buffer, do you?  And if so, how is that related to
the issue at hand, which is the doc string of that function?