[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#59603: 28.1.90; `ucs-normalize-string' fails to work
From: |
Ihor Radchenko |
Subject: |
bug#59603: 28.1.90; `ucs-normalize-string' fails to work |
Date: |
Sat, 26 Nov 2022 09:37:47 +0000 |
Eli Zaretskii <eliz@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>