GNU bug report logs - #59603
28.1.90; `ucs-normalize-string' fails to work

Previous Next

Full log

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

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59603 <at> debbugs.gnu.org
Subject: Re: bug#59603: 28.1.90; `ucs-normalize-string' fails to work
Date: Sat, 26 Nov 2022 09:37:47 +0000

Eli Zaretskii <eliz <at> gnu.org> writes:

>> I understand. But this macro is not private (no --). I feel like using
>> "str" there is a questionable code style.
>
> It's too late to change that: this macro is very old and predates the --
> conventions.

I see.

>> >> Also, no docstring.
>> >
>> > I added a doc string.
>> 
>> Thanks! The new docstring implies that STR is an argument, doesn't it?
>
> It doesn't.

I feel a bit confused now.

I am now reviewing D.6 Tips for Documentation Strings section of Elisp
manual:

   • When a function’s documentation string mentions the value of an
     argument of the function, use the argument name in capital letters
     as if it were a name for that value.  Thus, the documentation
     string of the function ‘eval’ refers to its first argument as
     ‘FORM’, because the actual argument name is ‘form’:

          Evaluate FORM and return its value.

     Also write metasyntactic variables in capital letters, such as when
     you show the decomposition of a list or vector into subunits, some
     of which may vary.  ‘KEY’ and ‘VALUE’ in the following example
     illustrate this practice:

          The argument TABLE should be an alist whose elements
          have the form (KEY . VALUE).  Here, KEY is ...

   • Never change the case of a Lisp symbol when you mention it in a doc
     string.  If the symbol’s name is ‘foo’, write “foo”, not “Foo”
     (which is a different symbol).

I do see that uppercase symbol names may not always refer to the
arguments, but don't `str' fit better into the conventions? It is the
symbol to be used in the macro, after all.
Or do I miss something?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Previous Next

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