Messages in this thread | | | Date | Fri, 26 May 2023 12:17:59 +0900 | Subject | Re: [PATCH 24/26] locking/atomic: scripts: generate kerneldoc comments | From | Akira Yokosawa <> |
| |
On Wed, 24 May 2023 16:11:52 +0200, Peter Zijlstra wrote: > On Wed, May 24, 2023 at 11:03:58PM +0900, Akira Yokosawa wrote: > >>> * All ops are described as an expression using their usual C operator. >>> For example: >>> >>> andnot: "Atomically updates @v to (@v & ~@i)" >> >> The kernel-doc script converts "~@i" into reST source of "~**i**", >> where the emphasis of i is not recognized by Sphinx. >> >> For the "@" to work as expected, please say "~(@i)" or "~ @i". >> My preference is the former. > > And here we start :-/ making the actual comment less readable because > retarded tooling. > >>> inc: "Atomically updates @v to (@v + 1)" >>> >>> Which may be clearer to non-naative English speakers, and allows all >> non-native >> >>> the operations to be described in the same style. >>> >>> * All conditional ops have their condition described as an expression >>> using the usual C operators. For example: >>> >>> add_unless: "If (@v != @u), atomically updates @v to (@v + @i)" >>> cmpxchg: "If (@v == @old), atomically updates @v to @new" >>> >>> Which may be clearer to non-naative English speakers, and allows all >> >> Ditto. > > How about we just keep it as is, and all the rst and html weenies learn > to use a text editor to read code comments?
:-) :-) :-)
It turns out that kernel-doc is aware of !@var [1]. Similar tricks can be added for ~@var. So let's keep it as is!
I'll ask documentation forks for updating kernel-doc when this change is merged eventually.
[1]: ee2aa7590398 ("scripts: kernel-doc: accept negation like !@var")
Thanks, Akira
| |