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. 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 >> >
