Re: [PATCH v3] doc/checkpatch: Add description to MACRO_ARG_REUSE

[Akira Yokosawa <akiyks@gmail.com>]

Hi,
Let me chime in.

On Wed, 6 Jul 2022 10:19:46 -0300, Martin Fernandez wrote:
> On 7/6/22, Bagas Sanjaya <bagasdotme@gmail.com> 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
>>
>