This is the mail archive of the
mailing list for the binutils project.
Re: [PATCH 2/6] Add opcodes support for Meta.
On Tue, 13 Nov 2012, Will Newton wrote:
> On Tue, Nov 13, 2012 at 5:04 PM, Joseph S. Myers
> <email@example.com> wrote:
> > There seem to be a lot of new functions in this patch that do not have a
> > comment above them explaining the semantics of the function, each
> > parameter and the return value, as per the GNU Coding Standards.
> Hi Joseph,
> Thanks for the review. Is there a specific file that is the issue? Is
> there a comparable port you would suggest that I could use as a
> reference for how it should be done?
I don't have a specific example to refer to. Just go through each new
function anywhere in this port (not just in this individual patch) and
make sure it has a comment above the function following what the GNU
Coding Standards say about such things:
Please put a comment on each function saying what the function does,
what sorts of arguments it gets, and what the possible values of
arguments mean and are used for. It is not necessary to duplicate in
words the meaning of the C argument declarations, if a C type is being
used in its customary fashion. If there is anything nonstandard about
its use (such as an argument of type char * which is really the address
of the second character of a string, not the first), or any possible
values that would not work the way one would expect (such as, that
strings containing newlines are not guaranteed to work), be sure to say
Also explain the significance of the return value, if there is one.
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".
There is usually no purpose in restating the name of the function in
the comment before it, because readers can see that for themselves.
There might be an exception when the comment is so long that the
function itself would be off the bottom of the screen.
That is, the comments should explain the interface, so that someone
looking at a call to one of the new functions can understand that call on
the basis of the comment on the function being called, without needing to
look at the details of the implementation inside the function.
If the function is implementing a standard hook that is called from
architecture-independent parts of binutils (as is especially likely to be
the case in the assembler) then there's less point in making the comment
go into details of each argument and the return value, since the semantics
of those will be whatever they are for the hook and are better documented
once rather than for every target architecture defining the hook.
Joseph S. Myers