* bug#57561: Improve documentation of seq-position @ 2022-09-03 13:00 Damien Cassou 2022-09-03 13:30 ` Lars Ingebrigtsen 0 siblings, 1 reply; 6+ messages in thread From: Damien Cassou @ 2022-09-03 13:00 UTC (permalink / raw) To: 57561 [-- Attachment #1: Type: text/plain, Size: 220 bytes --] Tags: patch Fix documentation of `seq-position' according to Eli Zaretskii's recommendation. -- Damien Cassou "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-Improve-documentation-of-seq-position.patch --] [-- Type: text/patch, Size: 1740 bytes --] From 093cb247148a965e5cd80056eff38d3ef6f288bb Mon Sep 17 00:00:00 2001 From: Damien Cassou <damien@cassou.me> Date: Sat, 3 Sep 2022 14:56:53 +0200 Subject: [PATCH] Improve documentation of seq-position * doc/lispref/sequences.texi (Sequence Functions): * lisp/emacs-lisp/seq.el (seq-position): Use more standard wording in the documentation of `seq-position'. --- doc/lispref/sequences.texi | 2 +- lisp/emacs-lisp/seq.el | 4 ++-- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 1f6f80521c..cc956952d6 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -863,7 +863,7 @@ Sequence Functions @end defun @defun seq-position sequence elt &optional function - This function returns the index of the first element in + This function returns the (zero-based) index of the first element in @var{sequence} that is equal to @var{elt}. If the optional argument @var{function} is non-@code{nil}, it is a function of two arguments to use instead of the default @code{equal}. diff --git a/lisp/emacs-lisp/seq.el b/lisp/emacs-lisp/seq.el index b6f0f66e5b..a121256146 100644 --- a/lisp/emacs-lisp/seq.el +++ b/lisp/emacs-lisp/seq.el @@ -435,8 +435,8 @@ seq-set-equal-p ;;;###autoload (cl-defgeneric seq-position (sequence elt &optional testfn) - "Return the index of the first element in SEQUENCE that is equal to ELT. -Equality is defined by TESTFN if non-nil or by `equal' if nil." + "Return the (zero-based) index of the first element in SEQUENCE that is equal to ELT. +Equality is defined by the function TESTFN, which defaults to `equal'." (let ((index 0)) (catch 'seq--break (seq-doseq (e sequence) -- 2.36.2 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* bug#57561: Improve documentation of seq-position 2022-09-03 13:00 bug#57561: Improve documentation of seq-position Damien Cassou @ 2022-09-03 13:30 ` Lars Ingebrigtsen 2022-09-03 14:23 ` Eli Zaretskii 2022-09-03 16:52 ` Damien Cassou 0 siblings, 2 replies; 6+ messages in thread From: Lars Ingebrigtsen @ 2022-09-03 13:30 UTC (permalink / raw) To: Damien Cassou; +Cc: 57561 Damien Cassou <damien@cassou.me> writes: > - "Return the index of the first element in SEQUENCE that is equal to ELT. > -Equality is defined by TESTFN if non-nil or by `equal' if nil." > + "Return the (zero-based) index of the first element in SEQUENCE that is equal to ELT. This makes the first line too long. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#57561: Improve documentation of seq-position 2022-09-03 13:30 ` Lars Ingebrigtsen @ 2022-09-03 14:23 ` Eli Zaretskii 2022-09-03 16:52 ` Damien Cassou 1 sibling, 0 replies; 6+ messages in thread From: Eli Zaretskii @ 2022-09-03 14:23 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: damien, 57561 > Cc: 57561@debbugs.gnu.org > From: Lars Ingebrigtsen <larsi@gnus.org> > Date: Sat, 03 Sep 2022 15:30:40 +0200 > > Damien Cassou <damien@cassou.me> writes: > > > - "Return the index of the first element in SEQUENCE that is equal to ELT. > > -Equality is defined by TESTFN if non-nil or by `equal' if nil." > > + "Return the (zero-based) index of the first element in SEQUENCE that is equal to ELT. > > This makes the first line too long. Yes. The usual fix would be Return the (zero-based) index of the first element in SEQUENCE equal to ELT. ^ permalink raw reply [flat|nested] 6+ messages in thread
* bug#57561: Improve documentation of seq-position 2022-09-03 13:30 ` Lars Ingebrigtsen 2022-09-03 14:23 ` Eli Zaretskii @ 2022-09-03 16:52 ` Damien Cassou 2022-09-03 16:56 ` Damien Cassou 1 sibling, 1 reply; 6+ messages in thread From: Damien Cassou @ 2022-09-03 16:52 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: 57561 [-- Attachment #1: Type: text/plain, Size: 629 bytes --] Lars Ingebrigtsen <larsi@gnus.org> writes: > Damien Cassou <damien@cassou.me> writes: >> - "Return the index of the first element in SEQUENCE that is equal to ELT. >> -Equality is defined by TESTFN if non-nil or by `equal' if nil." >> + "Return the (zero-based) index of the first element in SEQUENCE that is equal to ELT. > > This makes the first line too long. Indeed. I applied the change suggested by Eli. Also, the same sentence appeared several times in the file so the patch changes them all. -- Damien Cassou "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-Improve-documentation-of-seq-position.patch --] [-- Type: text/x-patch, Size: 4453 bytes --] From c198f7233081ddaee0e0f7c9872f58f602e37186 Mon Sep 17 00:00:00 2001 From: Damien Cassou <damien@cassou.me> Date: Sat, 3 Sep 2022 14:56:53 +0200 Subject: [PATCH] Improve documentation of seq-position * doc/lispref/sequences.texi (Sequence Functions): * lisp/emacs-lisp/seq.el (seq-position): Use more standard wording in the documentation of `seq-position'. --- doc/lispref/sequences.texi | 2 +- lisp/emacs-lisp/seq.el | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 1f6f80521c..cc956952d6 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -863,7 +863,7 @@ Sequence Functions @end defun @defun seq-position sequence elt &optional function - This function returns the index of the first element in + This function returns the (zero-based) index of the first element in @var{sequence} that is equal to @var{elt}. If the optional argument @var{function} is non-@code{nil}, it is a function of two arguments to use instead of the default @code{equal}. diff --git a/lisp/emacs-lisp/seq.el b/lisp/emacs-lisp/seq.el index b6f0f66e5b..23fed13c5d 100644 --- a/lisp/emacs-lisp/seq.el +++ b/lisp/emacs-lisp/seq.el @@ -409,7 +409,7 @@ seq-count (cl-defgeneric seq-contains (sequence elt &optional testfn) "Return the first element in SEQUENCE that is equal to ELT. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (declare (obsolete seq-contains-p "27.1")) (seq-some (lambda (e) (when (funcall (or testfn #'equal) elt e) @@ -418,7 +418,7 @@ seq-contains (cl-defgeneric seq-contains-p (sequence elt &optional testfn) "Return non-nil if SEQUENCE contains an element equal to ELT. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (catch 'seq--break (seq-doseq (e sequence) (let ((r (funcall (or testfn #'equal) e elt))) @@ -429,14 +429,14 @@ seq-contains-p (cl-defgeneric seq-set-equal-p (sequence1 sequence2 &optional testfn) "Return non-nil if SEQUENCE1 and SEQUENCE2 contain the same elements. This does not depend on the order of the elements. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (and (seq-every-p (lambda (item1) (seq-contains-p sequence2 item1 testfn)) sequence1) (seq-every-p (lambda (item2) (seq-contains-p sequence1 item2 testfn)) sequence2))) ;;;###autoload (cl-defgeneric seq-position (sequence elt &optional testfn) - "Return the index of the first element in SEQUENCE that is equal to ELT. -Equality is defined by TESTFN if non-nil or by `equal' if nil." + "Return the (zero-based) index of the first element in SEQUENCE equal to ELT. +Equality is defined by the function TESTFN, which defaults to `equal'." (let ((index 0)) (catch 'seq--break (seq-doseq (e sequence) @@ -502,7 +502,7 @@ seq-partition ;;;###autoload (cl-defgeneric seq-union (sequence1 sequence2 &optional testfn) "Return a list of all elements that appear in either SEQUENCE1 or SEQUENCE2. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (let* ((accum (lambda (acc elt) (if (seq-contains-p acc elt testfn) acc @@ -514,7 +514,7 @@ seq-union ;;;###autoload (cl-defgeneric seq-intersection (sequence1 sequence2 &optional testfn) "Return a list of the elements that appear in both SEQUENCE1 and SEQUENCE2. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (seq-reduce (lambda (acc elt) (if (seq-contains-p sequence2 elt testfn) (cons elt acc) @@ -524,7 +524,7 @@ seq-intersection (cl-defgeneric seq-difference (sequence1 sequence2 &optional testfn) "Return a list of the elements that appear in SEQUENCE1 but not in SEQUENCE2. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (seq-reduce (lambda (acc elt) (if (seq-contains-p sequence2 elt testfn) acc -- 2.36.2 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* bug#57561: Improve documentation of seq-position 2022-09-03 16:52 ` Damien Cassou @ 2022-09-03 16:56 ` Damien Cassou 2022-09-04 11:00 ` Lars Ingebrigtsen 0 siblings, 1 reply; 6+ messages in thread From: Damien Cassou @ 2022-09-03 16:56 UTC (permalink / raw) To: Lars Ingebrigtsen; +Cc: 57561 [-- Attachment #1: Type: text/plain, Size: 387 bytes --] Damien Cassou <damien@cassou.me> writes: > Indeed. I applied the change suggested by Eli. Also, the same sentence > appeared several times in the file so the patch changes them all. Here is the correct patch (the comment was changed). I'm sorry for the noise. -- Damien Cassou "Success is the ability to go from one failure to another without losing enthusiasm." --Winston Churchill [-- Warning: decoded text below may be mangled, UTF-8 assumed --] [-- Attachment #2: 0001-Improve-documentation-of-several-functions-in-seq.el.patch --] [-- Type: text/x-patch, Size: 4618 bytes --] From 1d1cd3180cabe814332a87090449c98fee556870 Mon Sep 17 00:00:00 2001 From: Damien Cassou <damien@cassou.me> Date: Sat, 3 Sep 2022 14:56:53 +0200 Subject: [PATCH] Improve documentation of several functions in seq.el Use more standard wording in the documentation of `seq-position'. * doc/lispref/sequences.texi (Sequence Functions): * lisp/emacs-lisp/seq.el (seq-contains): (seq-contains-p): (seq-set-equal-p): (seq-position): (seq-union): (seq-intersection): (seq-difference): Use more standard wording in the docstrings. --- doc/lispref/sequences.texi | 2 +- lisp/emacs-lisp/seq.el | 16 ++++++++-------- 2 files changed, 9 insertions(+), 9 deletions(-) diff --git a/doc/lispref/sequences.texi b/doc/lispref/sequences.texi index 1f6f80521c..cc956952d6 100644 --- a/doc/lispref/sequences.texi +++ b/doc/lispref/sequences.texi @@ -863,7 +863,7 @@ Sequence Functions @end defun @defun seq-position sequence elt &optional function - This function returns the index of the first element in + This function returns the (zero-based) index of the first element in @var{sequence} that is equal to @var{elt}. If the optional argument @var{function} is non-@code{nil}, it is a function of two arguments to use instead of the default @code{equal}. diff --git a/lisp/emacs-lisp/seq.el b/lisp/emacs-lisp/seq.el index b6f0f66e5b..23fed13c5d 100644 --- a/lisp/emacs-lisp/seq.el +++ b/lisp/emacs-lisp/seq.el @@ -409,7 +409,7 @@ seq-count (cl-defgeneric seq-contains (sequence elt &optional testfn) "Return the first element in SEQUENCE that is equal to ELT. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (declare (obsolete seq-contains-p "27.1")) (seq-some (lambda (e) (when (funcall (or testfn #'equal) elt e) @@ -418,7 +418,7 @@ seq-contains (cl-defgeneric seq-contains-p (sequence elt &optional testfn) "Return non-nil if SEQUENCE contains an element equal to ELT. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (catch 'seq--break (seq-doseq (e sequence) (let ((r (funcall (or testfn #'equal) e elt))) @@ -429,14 +429,14 @@ seq-contains-p (cl-defgeneric seq-set-equal-p (sequence1 sequence2 &optional testfn) "Return non-nil if SEQUENCE1 and SEQUENCE2 contain the same elements. This does not depend on the order of the elements. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (and (seq-every-p (lambda (item1) (seq-contains-p sequence2 item1 testfn)) sequence1) (seq-every-p (lambda (item2) (seq-contains-p sequence1 item2 testfn)) sequence2))) ;;;###autoload (cl-defgeneric seq-position (sequence elt &optional testfn) - "Return the index of the first element in SEQUENCE that is equal to ELT. -Equality is defined by TESTFN if non-nil or by `equal' if nil." + "Return the (zero-based) index of the first element in SEQUENCE equal to ELT. +Equality is defined by the function TESTFN, which defaults to `equal'." (let ((index 0)) (catch 'seq--break (seq-doseq (e sequence) @@ -502,7 +502,7 @@ seq-partition ;;;###autoload (cl-defgeneric seq-union (sequence1 sequence2 &optional testfn) "Return a list of all elements that appear in either SEQUENCE1 or SEQUENCE2. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (let* ((accum (lambda (acc elt) (if (seq-contains-p acc elt testfn) acc @@ -514,7 +514,7 @@ seq-union ;;;###autoload (cl-defgeneric seq-intersection (sequence1 sequence2 &optional testfn) "Return a list of the elements that appear in both SEQUENCE1 and SEQUENCE2. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (seq-reduce (lambda (acc elt) (if (seq-contains-p sequence2 elt testfn) (cons elt acc) @@ -524,7 +524,7 @@ seq-intersection (cl-defgeneric seq-difference (sequence1 sequence2 &optional testfn) "Return a list of the elements that appear in SEQUENCE1 but not in SEQUENCE2. -Equality is defined by TESTFN if non-nil or by `equal' if nil." +Equality is defined by the function TESTFN, which defaults to `equal'." (seq-reduce (lambda (acc elt) (if (seq-contains-p sequence2 elt testfn) acc -- 2.36.2 ^ permalink raw reply related [flat|nested] 6+ messages in thread
* bug#57561: Improve documentation of seq-position 2022-09-03 16:56 ` Damien Cassou @ 2022-09-04 11:00 ` Lars Ingebrigtsen 0 siblings, 0 replies; 6+ messages in thread From: Lars Ingebrigtsen @ 2022-09-04 11:00 UTC (permalink / raw) To: Damien Cassou; +Cc: 57561 Damien Cassou <damien@cassou.me> writes: > Here is the correct patch (the comment was changed). I'm sorry for the > noise. Thanks; pushed to Emacs 29. ^ permalink raw reply [flat|nested] 6+ messages in thread
end of thread, other threads:[~2022-09-04 11:00 UTC | newest] Thread overview: 6+ messages (download: mbox.gz follow: Atom feed -- links below jump to the message on this page -- 2022-09-03 13:00 bug#57561: Improve documentation of seq-position Damien Cassou 2022-09-03 13:30 ` Lars Ingebrigtsen 2022-09-03 14:23 ` Eli Zaretskii 2022-09-03 16:52 ` Damien Cassou 2022-09-03 16:56 ` Damien Cassou 2022-09-04 11:00 ` Lars Ingebrigtsen
Code repositories for project(s) associated with this public inbox https://git.savannah.gnu.org/cgit/emacs.git This is a public inbox, see mirroring instructions for how to clone and mirror all data and code used for this inbox; as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).