bug#59082: 28.2; Undocumented `intern-soft` feature with shorthands symbols

[Eli Zaretskii <eliz@gnu.org>]

> From: Richard Stallman <rms@gnu.org>
> Cc: eliz@gnu.org, thievol@posteo.net, 59082@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.