Date: Wed, 15 Feb 2012 23:01:51 +0100
From: Stefan Richter <stefanr@s5r6.in-berlin.de>
To: Chris Boot <bootc@bootc.net>
Cc: linux1394-devel@lists.sourceforge.net, target-devel@vger.kernel.org,
        linux-kernel@vger.kernel.org, agrover@redhat.com, clemens@ladisch.de,
        nab@linux-iscsi.org
Subject: Re: [PATCH v2 01/11] firewire: Add function to get speed from
 opaque struct fw_request
Message-ID: <20120215230151.3467cd8a@stein>
In-Reply-To: <4F3C0333.6060306@bootc.net>
References: <1328989452-20921-1-git-send-email-bootc@bootc.net>
	<1329317248-94128-1-git-send-email-bootc@bootc.net>
	<1329317248-94128-2-git-send-email-bootc@bootc.net>
	<20120215200919.10d9e2eb@stein>
	<4F3C0333.6060306@bootc.net>
Mime-Version: 1.0
Content-Type: text/plain; charset=US-ASCII
Content-Transfer-Encoding: 7bit
Sender: linux-kernel-owner@vger.kernel.org
Content-Length: 2368
Lines: 65

On Feb 15 Chris Boot wrote:
> On 15/02/2012 19:09, Stefan Richter wrote:
> > On Feb 15 Chris Boot wrote:
> >> --- a/drivers/firewire/core-transaction.c
> >> +++ b/drivers/firewire/core-transaction.c
> >> @@ -820,6 +820,22 @@ void fw_send_response(struct fw_card *card,
> >>   }
> >>   EXPORT_SYMBOL(fw_send_response);
> >>
> >> +/**
> >> + * fw_get_request_speed() - Discover bus speed used for this request
> >> + * @request:	The struct fw_request from which to obtain the speed.
> >> + *
> >> + * In certain circumstances it's important to be able to obtain the speed at
> >> + * which a request was made to an address handler, for example when
> >> + * implementing an SBP-2 or SBP-3 target. This function inspects the response
> >> + * object to obtain the speed, which is copied from the request packet in
> >> + * allocate_request().
> >> + */
> >> +int fw_get_request_speed(struct fw_request *request)
> >> +{
> >> +	return request->response.speed;
> >> +}
> >> +EXPORT_SYMBOL(fw_get_request_speed);
> >
> > Uh oh, what have I done by asking for a comment? :-)
> >
> > Can you tell what's wrong with this API documentation?
> 
> Better to have too much than too little? :-)
> 
> Linux 3.4, now with added Enterprise.
> 
> Shall I cut it down a bit?

a)  The implementation of the function should not be explained here;
after all it is meant to be opaque to API users.  Besides, if somebody
changes the implementation he will for sure forget to change the comment.

b)  It is fairly self-evident at which occasions an API user would want
to use this function.  (Everytime when he needs to know that speed.)

c)  The function call argument does not really need to be explained
either as soon as the purpose of the function has been made known.

So in my first response where I already acked your patch I should have
simply asked for

/**
 * fw_get_request_speed() - returns speed at which the @request was received
 */

to be added to your patch.  :-)

Patch review could be so easy for everyone involved if the reviewer knew
how to express himself...
-- 
Stefan Richter
-=====-===-- --=- -====
http://arcgraph.de/sr/
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/