Re: [PATCH+8.3?] Implement dump of mappings with ELF headers by gcore

[Pedro Alves <palves@redhat.com>]

On 4/25/19 10:04 PM, Kevin Buettner wrote:
> On Thu, 25 Apr 2019 14:24:39 -0400
> Sergio Durigan Junior <sergiodj@redhat.com> wrote:
> 
>>>> 	* linux-tdep.c (dump_mapping_p): Add new parameters "ADDR" and
>>>> 	"OFFSET".  Verify if current mapping contains an ELF header.
>>>> 	(linux_find_memory_regions_full): Adjust call to
>>>> 	"dump_mapping_p".  
>>>
>>> I don't think that the double quotes enclosing ADDR and OFFSET are
>>> needed here.  
>>
>> Ah, OK.  I tend to use them when I'm writing ChangeLog entries, but
>> that's a matter of style.  I'll remove them.
> 
> I think that quotes are appropriate when the actual names of the
> parameters are used.  But (as I recall) the GNU convention is to
> change the names to all caps when referring to parameters in
> documentation.  ChangeLog entries are a form of documenation, so no
> quotes. 

All caps is used when referring to the values of the parameters, not
the parameters themselves.
From <https://www.gnu.org/prep/standards/standards.html>:

 "The comment on a function is much clearer if you use the argument
  names to speak about the argument values. The variable name itself
  should be lower case, but write it in upper case when you are
  speaking about the value rather than the variable itself. Thus,
  “the inode number NODE_NUM” rather than “an inode”. "

So in this case it should be lowercase, since you're talking about the name of
the variable/parameter.

I usually say "New parameter 'parameter'.", with single quotes.  You can
find past examples in the ChangeLogs.

Thanks,
Pedro Alves