Possible typo in vc.el

Possible typo in vc.el

[Omar Polo]

Hello,

in vc.el, in the comment at the start of the file where the vc interface
is described, for `log-search' only the `pattern' argument is mentioned
(and this matches the signature of vc-log-search), BUT the
vc-SYS-log-search (where sys is a backend) is called with *two*
arguments: the buffer where to store the result and the pattern.

Now, the text in vc.el makes me think that the list of function and
their description in the comment is intended as documentation of the vc
interface that a backend has to implement, not as documentation of the
user-facing functions.  Am I right?

Thanks,

Omar Polo

Re: Possible typo in vc.el

[Juri Linkov]

[-- Attachment #1: Type: text/plain, Size: 726 bytes --]

> Hello,
>
> in vc.el, in the comment at the start of the file where the vc interface
> is described, for `log-search' only the `pattern' argument is mentioned
> (and this matches the signature of vc-log-search), BUT the
> vc-SYS-log-search (where sys is a backend) is called with *two*
> arguments: the buffer where to store the result and the pattern.
>
> Now, the text in vc.el makes me think that the list of function and
> their description in the comment is intended as documentation of the vc
> interface that a backend has to implement, not as documentation of the
> user-facing functions.  Am I right?

Yes, you are right.  The comment in vc.el should describe the backend API.
So here is the patch that fixes this:


[-- Warning: decoded text below may be mangled, UTF-8 assumed --]
[-- Attachment #2: vc-api.patch --]
[-- Type: text/x-diff, Size: 2849 bytes --]

diff --git a/lisp/vc/vc.el b/lisp/vc/vc.el
index d36baacfe8..6d1e89e42b 100644
--- a/lisp/vc/vc.el
+++ b/lisp/vc/vc.el
@@ -201,7 +201,7 @@
 ;;
 ;; STATE-CHANGING FUNCTIONS
 ;;
-;; * create-repo (backend)
+;; * create-repo ()
 ;;
 ;;   Create an empty repository in the current directory and initialize
 ;;   it so VC mode can add files to it.  For file-oriented systems, this
@@ -275,7 +275,7 @@
 ;;   If FILE is in the `added' state it should be returned to the
 ;;   `unregistered' state.
 ;;
-;; - merge-file (file rev1 rev2)
+;; - merge-file (file &optional rev1 rev2)
 ;;
 ;;   Merge the changes between REV1 and REV2 into the current working
 ;;   file (for non-distributed VCS).  It is expected that with an
@@ -333,19 +333,19 @@
 ;;   the case).  Not all backends support this.  At present, this is
 ;;   only ever used with LIMIT = 1 (by vc-annotate-show-log-revision-at-line).
 ;;
-;; * log-outgoing (backend remote-location)
+;; * log-outgoing (buffer remote-location)
 ;;
 ;;   Insert in BUFFER the revision log for the changes that will be
 ;;   sent when performing a push operation to REMOTE-LOCATION.
 ;;
-;; * log-incoming (backend remote-location)
+;; * log-incoming (buffer remote-location)
 ;;
 ;;   Insert in BUFFER the revision log for the changes that will be
 ;;   received when performing a pull operation from REMOTE-LOCATION.
 ;;
-;; - log-search (pattern)
+;; - log-search (buffer pattern)
 ;;
-;;   Search for PATTERN in the revision log.
+;;   Search for PATTERN in the revision log and output results into BUFFER.
 ;;
 ;; - log-view-mode ()
 ;;
@@ -478,7 +478,7 @@
 ;;
 ;;   Return the root of the VC controlled hierarchy for file.
 ;;
-;; - ignore (file &optional directory)
+;; - ignore (file &optional directory remove)
 ;;
 ;;   Ignore FILE under DIRECTORY (default is 'default-directory').
 ;;   FILE is a file wildcard relative to DIRECTORY.
@@ -487,7 +487,7 @@
 ;;   When called from Lisp code, if DIRECTORY is non-nil, the
 ;;   repository to use will be deduced by DIRECTORY.
 ;;
-;; - ignore-completion-table
+;; - ignore-completion-table (directory)
 ;;
 ;;   Return the completion table for files ignored by the current
 ;;   version control system, e.g., the entries in `.gitignore' and
diff --git a/lisp/vc/vc-git.el b/lisp/vc/vc-git.el
index fd19008dee..ad6e4de736 100644
--- a/lisp/vc/vc-git.el
+++ b/lisp/vc/vc-git.el
@@ -72,7 +72,7 @@
 ;;                                          by git, so it's probably
 ;;                                          not a good idea.
 ;; - merge-news (file)                      see `merge-file'
-;; - mark-resolved (file)                          OK
+;; - mark-resolved (files)                         OK
 ;; - steal-lock (file &optional revision)          NOT NEEDED
 ;; HISTORY FUNCTIONS
 ;; * print-log (files buffer &optional shortlog start-revision limit)   OK

Re: Possible typo in vc.el

[Dmitry Gutov]

On 05.12.2020 22:24, Juri Linkov wrote:
> Yes, you are right.  The comment in vc.el should describe the backend API.
> So here is the patch that fixes this:

Thanks, Juri!