bug#63896: [PATCH] Support annotating and sorting the project list during completion

[Eli Zaretskii <eliz@gnu.org>]

> From: Spencer Baugh <sbaugh@janestreet.com>
> Date: Sun, 04 Jun 2023 17:20:19 -0400
> 
> This patch adds an annotation-function and display-sort-function to the
> completion-table used for project-prompt-project-dir and
> project-prompt-project-name, as well as a user customization variable to
> customize the behavior of the annotation and sorting functions.

Thanks.  A few minor comments.

> +(defun project-annotation-numbufs (pr)
> +  "Annotate PROJECT with the length of `project-buffers'."

The argument is named PR, not PROJECT.

Also, instead if too-technical "length of `project-buffers'", how
about saying "number of buffers in the project", or "number of buffers
in `project-buffers'"?

> +(defun project-annotation-mtime (pr)
> +  "Annotate PROJECT with the modification time of its root directory.

PR, not PROJECT.

> +Note that the modification time will only change when files
> +directly under the root directory are added or deleted.  If you
> +only add or delete files in subdirectories, or if you only modify
> +existing files, the modification time won't change."

This is not guaranteed, so I'd suggest to mention that the reliability
of this annotation is questionable, and depends on the underlying
filesystem.

> +(defun project-annotation-compilation (project)
> +  "Annotate PROJECT with information from its compilation buffer if any."

I'd add here something about that "information".  Right now, this doc
string is not very useful.

> +          (cons (+ (* 100 compilation-num-errors-found)
> +                   (* 10 compilation-num-warnings-found)

Why "encode" these numbers in a single value? why not use a cons or a
vector?

> +                (format-mode-line mode-line-process nil nil buf)))

Do you really need to call format-mode-line?  My advice is to stay
away of that function: it could have unpleasant side effects.