GNU bug report logs - #59082
28.2; Undocumented `intern-soft` feature with shorthands symbols

Previous Next

Full log

Message #41 received at 59082 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: rms <at> gnu.org
Cc: thievol <at> posteo.net, joaotavora <at> gmail.com, 59082 <at> debbugs.gnu.org
Subject: Re: bug#59082: 28.2;
 Undocumented `intern-soft` feature with shorthands symbols
Date: Mon, 14 Nov 2022 15:05:33 +0200

> From: Richard Stallman <rms <at> gnu.org>
> Cc: eliz <at> gnu.org, thievol <at> posteo.net, 59082 <at> debbugs.gnu.org
> Date: Sun, 13 Nov 2022 22:13:00 -0500
> 
> But if a doc string in s.el actually says "Calls the function
> `s-foo'", nothing will translate that to `string-foo', So we will get
> incorrect and confusing output.
> 
> Does any doc string in s.el actually use the name of a function or
> variable in s.el?

It does.  Here are a few examples:

  (defun s-split-up-to (separator s n &optional omit-nulls)
    "Split S up to N times into substrings bounded by matches for regexp SEPARATOR.

  If OMIT-NULLS is non-nil, zero-length substrings are omitted.

  See also `s-split'."

  (defun s-ends-with? (suffix s &optional ignore-case)
    "Does S end with SUFFIX?

  If IGNORE-CASE is non-nil, the comparison is done without paying
  attention to case differences.

  Alias: `s-suffix?'"

  (defun s-presence (s)
    "Return S if it's `s-present?', otherwise return nil."

  (defun s-count-matches-all (regexp s &optional start end)
    "Count occurrences of `regexp' in `s'.

  `start', inclusive, and `end', exclusive, delimit the part of `s' to
  match.  `start' and `end' are both indexed starting at 1; the initial
  character in `s' is index 1.

  This function starts looking for the next match from the second
  character of the previous match.  Hence, it counts matches that
  overlap a previously found match.  To ignore matches that overlap a
  previously found match, use `s-count-matches'."

I think it really is such a widespread (and good) practice to include
cross-references in doc strings that it should be a no-brainer to
decide that supporting this practice is important.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.