GNU bug report logs -
#75290
Fwd: remove-pos-from-symbol and bare-symbol
Previous Next
Full log
Message #11 received at 75290 <at> debbugs.gnu.org (full text, mbox):
Alan Mackenzie <acm <at> muc.de> 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 <rms <at> gnu.org>
>> To: emacs-devel <at> gnu.org
>> 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?
This bug report was last modified 78 days ago.
Previous Next
GNU bug tracking system
Copyright (C) 1999 Darren O. Benham,
1997,2003 nCipher Corporation Ltd,
1994-97 Ian Jackson.