Subject: bug#27764: 26.0.50; Argument STARTUP-HOOKS for `ediff-files' undocumented

From: Eli Zaretskii <[email-masked]>
Date: Fri, 29 Sep 2017 10:17:49 +0300

> From: Philipp Stephani <[email-masked]>
> Date: Sun, 24 Sep 2017 08:00:53 +0000
> Cc: [email-masked]
> 
>  > (defun ediff-buffers (buffer-A buffer-B &optional startup-hooks job-name)
>  > - "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B."
>  > + "Run Ediff on a pair of buffers, BUFFER-A and BUFFER-B.
>  > +STARTUP-HOOKS is a list of functions that Emacs calls without
>  > +arguments after setting up the Ediff buffers. JOB-NAME is a
>  > +symbol describing the Ediff job type; it defaults to
>  > +`ediff-buffers'."
> 
>  Here and elsewhere where JOB-NAME is mentioned, it would be good to
>  have a full list of supported symbols, not just the default one.
> 
> I've added some generic text to the docstrings. I have no idea what the full list of supported symbols are and
> what the point of this argument is in the first place. 

Can we have there at least the list of the symbols that are seen in
the sources:  I see these:

 ediff-merge-files-with-ancestor, ediff-last-dir-ancestor,
 ediff-last-dir-C, ediff-buffers, ediff-buffers3, ediff-merge-buffers,
 ediff-merge-buffers-with-ancestor

If this list is too long to be repeated in each doc string, we could
have it once, and reference that place from the other do strings.  I
think either way would be much better than using some generic text.

OK?

Thanks.