On 7/6/22, Akira Yokosawa <akiyks@xxxxxxxxx> wrote: > Hi, > Let me chime in. > > On Wed, 6 Jul 2022 10:19:46 -0300, Martin Fernandez wrote: >> On 7/6/22, Bagas Sanjaya <bagasdotme@xxxxxxxxx> wrote: >>> On Mon, Jul 04, 2022 at 07:57:57PM -0300, Martin Fernandez wrote: >>>> + **ARG_REUSE** >>>> + Using the same argument multiple times in the macro definition >>>> + would lead to unwanted side-effects. >>>> + >>>> + For example, given a `min` macro defined like:: >>>> + >>>> + #define min(x, y) ((x) < (y) ? (x) : (y)) >>>> + >>>> + If you call it with `min(foo(x), 0)`, it would expand to:: >>>> + >>>> + foo(x) < 0 ? foo(x) : 0 >>>> + >>> >>> Nit: literal blocks are indented three spaces relative to surrounding >>> paragraph. >> >> I just been told that I should be using 2 (I was using 1) and the rest >> of the file have 2 spaces... > > I think what Bagas said above is convention of Python documentation [1]. > As far I see, there is no such convention in kernel documentation. > Indents of 2 spaces are fine as far as they are consistent in > related .rst files, I suppose. > > [1]: https://devguide.python.org/documenting/#use-of-whitespace > >> >>>> + If `foo` has side-effects or it's an expensive calculation the >>>> + results might not be what the user intended. >>>> + >>>> + For a workaround the idea is to define local variables to hold the >>>> + macro's arguments. Checkout the actual implementation of `min` in >>>> + include/linux/minmax.h for the full implementation of the >>>> + workaround. >>>> + >>> >>> For inline code, the correct syntax is ``some text``. >> >> You are right, I just misleadingly reused the syntax for some other >> example in the file. >> >>> However, by >>> convention here, the backquotes aren't used where these would be >>> appropriate, like variable and function names. >> >> So you are saying that for single variables and functions you don't >> use double backquotes? > > If you want crossref from the functions to their kernel-doc definitions, > you can just say function() --- no double backquotes. > If you say ``function()``, crossref won't work. See [2] for such > crossrefs. > > [2]: > https://www.kernel.org/doc/html/latest/doc-guide/kernel-doc.html#cross-referencing-from-restructuredtext > > For simple variables, the style is up to you. Too much double > backquotes might make the text hard to read as plain text, though. Great! Thanks for clearing both doubts! > Thanks, Akira > >> >>> For the last paragraph, better say "The workaround is to define local >>> variables to hold macro arguments. See the min macro in >>> include/linux/minmax.h for example.". >> >> I like it. Thanks. >> >>> -- >>> An old man doll... just what I always wanted! - Clara >>> >> >
