Some points on clang-format usage

[Stephan Bergmann]

On 12/14/2017 10:35 AM, Miklos Vajna wrote:
> On Wed, Dec 13, 2017 at 10:50:31AM +0100, Stephan Bergmann <sbergman at redhat.com> wrote:
>> Another gotcha to watch out for related to comments is how
>>
>>> void decl1(); // lengthy comment comment comment comment comment comment comment comment comment
>>>                // comment comment comment comment comment comment comment comment pertaining to decl1
>>> void decl2();
>>>      // lengthy comment comment comment comment comment comment comment comment pertaining to decl2
>>> void decl3();
>>>
>>> void f() {
>>>      statement1(); // lengthy comment comment comment comment comment comment comment comment comment
>>>                    // comment comment comment comment comment comment pertaining to statement1
>>>      statement2();
>>>          // lengthy comment comment comment comment comment comment comment pertaining to statement2
>>>      statement3();
>>> }
>>
>> is reformatted to
>>
>>> void decl1(); // lengthy comment comment comment comment comment comment comment comment comment
>>>      // comment comment comment comment comment comment comment comment pertaining to decl1
> 
> This is due to our explicit AlignTrailingComments=false, it may make
> sense to consider enabling it (if
> solenv/clang-format/reformat-formatted-files confirms this solves more
> problems than it causes).
> 
>>> void decl2();
>>> // lengthy comment comment comment comment comment comment comment comment pertaining to decl2
>>> void decl3();
> 
> I think this style was discussed on IRC already, and there was no
> consensus if even the original form is misleading to the reader of the
> code or not (so I did not research so far if there is an option to
> preserve that style).

I now find that my examples above didn't even show what actually pissed 
me off when I tried to get a comment past clang-format in 
<https://cgit.freedesktop.org/libreoffice/core/commit/?id=a31267be1bb42> 
"Fix isSalCallFunction so it also works on Windows".

Namely the inconsistency in reformatting from

> void decl1(); // lengthy comment comment comment comment comment comment comment comment
>               // comment comment comment comment comment comment comment pertaining to decl1
> void decl2() {} // lengthy comment comment comment comment comment comment comment comment
>                 // comment comment comment comment comment comment comment pertaining to decl2
> void decl3();

to

> void decl1(); // lengthy comment comment comment comment comment comment comment comment
>     // comment comment comment comment comment comment comment pertaining to decl1
> void decl2() {} // lengthy comment comment comment comment comment comment comment comment
> // comment comment comment comment comment comment comment pertaining to decl2
> void decl3();

treating comments following function definitions differently than those 
following mere function declarations.