Re: style convention: /*foo_p=*/ to annotate bool arguments

[Pedro Alves <pedro at palves dot net>]

On 10/05/2016 05:12 PM, Jeff Law wrote:
> On 10/04/2016 03:08 PM, Jason Merrill wrote:
>> On Tue, Oct 4, 2016 at 4:29 PM, Zan Lynx <zlynx@acm.org> wrote:
>>> On 10/04/2016 02:00 PM, Martin Sebor wrote:
>>>> This would have been easier if C++ had allowed the same default
>>>> value to
>>>> be given in both the declaration and the definition:
>>>>
>>>> void foo(int x, int y, bool bar_p = false);
>>>>
>>>> void foo(int x, int y, bool bar_p = false)
>>>> {
>>>> }
>>>
>>> There is really no point to duplicating it. The default value goes into
>>> the headers which is what is read by users of the code.
>>
>> In GCC sources, I think users look at the function definition more
>> often than the declaration in the header, the latter of which
>> typically has neither comments nor parameter names.
> So true.  One could claim that our coding standards made a fundamental
> mistake -- by having all the API documentation at the implementation
> rather than at the declaration.  Sigh....

It's never too late.  GDB used to be like that, and a few
years ago we've decided to start putting comments in the headers instead.  We
haven't done a mass conversion.  Simply new extern functions
get documented at the declaration instead of implementation, and we
also generally move the comment when we're making a static function  
extern.  Over time, old code is moved around or rewritten, and
comments migrate to API headers.  I think that has been a good idea.
Particularly more so for headers defining some module's public API.