GNU bug report logs -
#75290
Fwd: remove-pos-from-symbol and bare-symbol
Previous Next
Full log
Message #14 received at 75290 <at> debbugs.gnu.org (full text, mbox):
Hello, Stefan.
On Sat, Mar 01, 2025 at 20:17:53 -0800, Stefan Kangas wrote:
> 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?
I'm afraid I need to decline such requests. I'm no longer working on
Emacs (except for CC Mode, and possibly things I'm "responsible" for).
I'm now working on other things.
Sorry.
--
Alan Mackenzie (Nuremberg, Germany).
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.