bug#16687: 24.3.50; completion doc errors

bug#16687: 24.3.50; completion doc errors

[Leo Liu]

The doc disagrees with the function's doc-string:

,----[ (info "(elisp)Completion Variables") ]
|      The TRY-COMPLETION and ALL-COMPLETIONS functions should each
|      accept four arguments: STRING, COLLECTION, PREDICATE, and POINT.
|      The STRING, COLLECTION, and PREDICATE arguments have the same
|      meanings as in `try-completion' (*note Basic Completion::), and
|      the POINT argument is the position of point within STRING.  Each
|      function should return a non-`nil' value if it performed its job,
|      and `nil' if it did not (e.g., if there is no way to complete
|      STRING according to the completion style).
`----

It seems this should be `five' instead of `four':

,----[ (info "(elisp)Programmed Completion") ]
|    * A flag specifying the type of completion operation to perform.
|      This is one of the following four values:
`----

Leo

bug#16687: 24.3.50; completion doc errors

[N. Jackson]

Hi Leo,

At 09:31 +0800 on Saturday 2014-02-08, Leo Liu wrote:
>
> The doc disagrees with the function's doc-string:
>
> ,----[ (info "(elisp)Completion Variables") ]
> |      The TRY-COMPLETION and ALL-COMPLETIONS functions should each
> |      accept four arguments: STRING, COLLECTION, PREDICATE, and
> |      POINT. The STRING, COLLECTION, and PREDICATE arguments have
> |      the same meanings as in `try-completion' (*note Basic
> |      Completion::), and the POINT argument is the position of
> |      point within STRING. Each function should return a non-`nil'
> |      value if it performed its job, and `nil' if it did not (e.g.,
> |      if there is no way to complete STRING according to the
> |      completion style).
> `----

To which function are you referring? This is the doc of the _variable_
`completion-styles-alist'.

If you mean the function `try-completion', the doc doesn't say that
the TRY-COMPLETION and ALL-COMPLETIONS functions should have the same
"signature" as `try-completion', only that their arguments named
STRING, COLLECTION, and PREDICATE have the same meaning as the
arguments, with the same names, to `try-completion'.

The docstring of `try-completion' indeed documents the meaning of
these three arguments and I don't see any obvious inconsistency there.

Can you be more specific about the inconsistency you see?

> It seems this should be `five' instead of `four':
>
> ,----[ (info "(elisp)Programmed Completion") ]
> |    * A flag specifying the type of completion operation to
> |    perform. This is one of the following four values:
> `----

This bit of documention now reads:

   • A flag specifying the type of completion operation to perform.
     This flag may be one of the following values.

So this part of the bug is now fixed. :)

N.