[PATCH] Avoid starting a comment with */*

[Peter Harris]

On 2014-03-11 01:45, Thomas Klausner wrote:
>> -extern _X_EXPORT Bool AddCallback(CallbackListPtr * /*pcbl */ ,
>> -                                  CallbackProcPtr /*callback */ ,
>> -                                  void */*data */ );
>> +extern _X_EXPORT Bool AddCallback(CallbackListPtr *pcbl,
>> +                                  CallbackProcPtr callback,
>> +                                  void *data);
> 
> I was always told that I should avoid function argument names in
> prototypes in header files because they can break when macros are
> used; but this patch adds such names.

Huh. I assumed it was some pre-ANSI thing, but I never bothered to check.

In my experience, some editors with ctags-like functionality provide
better documentation when names are present (although to be honest,
commented names might be included too). I was not previously familiar
with the "when macros are used" problem. After some searching, I presume
you refer to
https://www.securecoding.cert.org/confluence/display/seccode/API08-C.+Avoid+parameter+names+in+a+function+prototype

That's at least mildly silly. If the same names are used in the function
declaration as are used in the function definition, even their contrived
"does not result in a syntax error" example will be a syntax error at
the function definition site. And, indeed, their "search CERT for this
vulnerability" link returns "No results found".

https://www.kb.cert.org/vulnotes/bymetric?searchview&query=FIELD+KEYWORDS+contains+API08-C

> Does adding a space in '*/*', i.e. making it '* /*', also work?
> 
> Like this:
> extern _X_EXPORT Bool AddCallback(CallbackListPtr * /* pcbl */,
>                                   CallbackProcPtr /* callback */,
>                                   void * /* data */);

Yes, that also works.

There are instances of both (named parameters, and * /* ) already in
some of those header files. I just picked one option at random.

Thanks for reviewing.

Peter Harris
-- 
               Open Text Connectivity Solutions Group
Peter Harris                    http://connectivity.opentext.com/
Research and Development        Phone: +1 905 762 6001
pharris at opentext.com            Toll Free: 1 877 359 4866