Subject: Re: bug#75290: Fwd: remove-pos-from-symbol and bare-symbol

From: Stefan Kangas <[email-masked]>
Date: Sat, 1 Mar 2025 20:17:53 -0800

Alan Mackenzie <[email-masked]> writes:

> Hello, Stefan.
>
> Thanks for the Cc:.
>
> On Thu, Jan 02, 2025 at 11:22:44 -0600, Stefan Kangas wrote:
>> Severity: wishlist
>
>> I'm forwarding this to the bug tracker so that we don't lose track of
>> it.  Alan, any comments here?
>
> Yes.  I remember vaguely having some difficulty formulating these doc
> strings.  Making them accurate would have made them less readable.  So I
> erred on the side of sketchy rather than unreadable.  I underestimated
> the amount of difficulty this would cause.
>
>> -------------------- Start of forwarded message --------------------
>> From: Richard Stallman <[email-masked]>
>> To: [email-masked]
>> Subject: remove-pos-from-symbol and bare-symbol
>> Date: Sun, 10 Mar 2024 22:39:23 -0400
>
>> [[[ To any NSA and FBI agents reading my email: please consider    ]]]
>> [[[ whether defending the US Constitution against all enemies,     ]]]
>> [[[ foreign or domestic, requires you to follow Snowden's example. ]]]
>
>> The doc string of remove-pos-from-symbol says to compare it with
>> bare-symbol.  The doc strings are too sketchy to make clear what the
>> difference is.  Someone who knows should make that clear.
>
>> Is the difference what they do to an argument that is not a symbol?
>
> Yes.  bare-symbol signals an error, remove-pos-from-symbol returns a
> non-symbol argument unchanged.
>
>> If so, it would be good to state that explicitly in the doc string
>> of bare-symbol.  "If need be" is not explicit, not concrete.
>
> OK.  The current doc string for bare-symbol is:
>
>     Extract, if need be, the bare symbol from SYM.
>     SYM is either a symbol or a symbol with position.
>     Ignore `symbols-with-pos-enabled'.
>
> How about the following replacement?
>
>     Extract and return the bare symbol from SYM, when it is a symbol
>     with position.  Return SYM unchanged when it is a symbol.  Otherwise
>     signal an error.  Ignore `symbols-with-pos-enable'.
>
>     Compare with `remove-pos-from-symbol'.

Richard, could you please comment on this?

>> I tried looking at the macros they call, which are in lisp.h.  But
>> those don't have doc strings and just call other functions that have
>> no comments to say what they do.
>
>> The macros and inline functions in lisp.h need to be documented there.
>
> I agree, this is bad and needs rectifying.  The time taken to fix this
> would be less than the time wasted by people reading it and having to
> figure out for themselves what each macro/function does.
>
> When I added symbols with position to this part of lisp.h, I just did so
> in the style of the existing code, i.e. undocumented.
>
> I think somebody should fix it now.

Would you be willing to propose such docstrings?