This is the mail archive of the binutils@sourceware.org mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

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
> <joseph@codesourcery.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
   so.

   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.

http://www.gnu.org/prep/standards/html_node/Comments.html

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
joseph@codesourcery.com


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]