Re: [PATCH 3/4] Intel PTI implementaiton of MIPI 1149.7.

[Randy Dunlap]

On Thu, 21 Apr 2011 14:06:39 -0700 J Freyensee wrote:

> On Wed, 2011-04-20 at 16:10 -0700, Randy Dunlap wrote:
> > On Wed, 20 Apr 2011 16:05:00 -0700 J Freyensee wrote:
> > 
> > > On Tue, 2011-04-19 at 16:15 -0700, Randy Dunlap wrote:
> > > 
> > > A couple more comments below.
> > > 
> > > > On Tue, 19 Apr 2011 15:58:08 -0700 james_p_freyensee@xxxxxxxxxxxxxxx wrote:
> > 
> > 
> > > > > + * @max_IDS: The max amount of available write IDs to use.
> > > > > + * @baseID:  The starting SW channel ID, based on the Intel
> > > > > + *           PTI arch.
> > > > > + *
> > > > > + * @return: pti_masterchannel struct containing master, channel ID address,
> > > > 
> > > > No '@' on "return".
> > > 
> > > Why no '@' on 'return' when just by doing a 'grep -Ri "@return" drivers/
> > > | wc -l' I count 369 examples of '@return' being used already in the
> > > kernel?  It looks like an acceptable format to me.
> > 
> > It's not.  See Documentation/kernel-doc-nano-HOWTO.txt.
> > '@' goes on function parameters (or struct members).
> > Not on return values.  Those other places should be fixed, but
> > it's just not a high priority thing to do.
> > 
> 
> How should I document return values of functions?  I would like them
> documented somehow.

Agreed.

Just use something like:

 * Returns:
 *	0 for success
 *	error code < 0 for errors


> kernel-doc-nano-HOWTO.txt does not say other than give examples of what
> I don't want to do and to 'Take a look around the source tree for
> examples'.  
> 
> So one example I found that documents return values does not seem to
> follow kernel-doc-nano-HOWTO.txt:
> 
> (acpi/acpica/dsutils.c)
>  /*******************************************************************************
>  *
>  * FUNCTION:    acpi_ds_clear_implicit_return
>  *
>  * PARAMETERS:  walk_state          - Current State
>  *
>  * RETURN:      None.
>  *

Yes, I know that there are several that don't do so.
And at least in this case, they have a reason:  acpica is portable code,
not specific to Linux.


> then another driver, net/wireless/libertas/tx.c, does exactly what I do
> that I'm being advised against (minus the 's' at the end of 'return'):
> 
> /**
>  *  @brief This function sends to the host the last transmitted packet,
>  *  filling the radiotap headers with transmission information.
>  *
>  *  @param priv     A pointer to struct lbs_private structure
>  *  @param status   A 32 bit value containing transmission status.
>  *
>  *  @returns void
>  */

I'll be glad to send them email about this.  Thanks for noticing.


> > > > > + * or 0 for error.
> > > > > + *
> > > > > + * Each bit in the arrays ia_app and ia_os correspond to a master and
> > > > > + * channel id. The bit is one if the id is taken and 0 if free. For
> > > > > + * every master there are 128 channel id's.
> > > > > + */
> > > > > +static struct pti_masterchannel *getID(u8 *IDarray, int max_IDS, int baseID)
> > > > > +{
> > 
> > 
> > > > > +/**
> > > > > + * pti_request_masterchannel() - Kernel API function used to allocate
> > > > > + *                                a master, channel ID address to write to
> > > > > + *                                PTI HW.
> > > > > + * @type: 0- request Application  master, channel aperture ID write address.
> > > > > + *        1- request OS master, channel aperture ID write address.
> > > > > + *        2- request Modem master, channel aperture ID write
> > > > > + *           address.
> > > > > + *        Other values, error.
> > > > > + * @return: pti_masterchannel struct or 0 for error.
> > > > 
> > > > No '@' on "return".
> > > 
> > > Same reason here.
> > 
> > Same answer here.
> > 
> > 
> > 
> > > > > + *
> > > > > + * @return int : Success = 0, otherwise fail.
> > > > 
> > > > No '@' on "return".
> > > 
> > > Same explanation as above.
> > 
> > Same reply also.


---
~Randy
*** Remember to use Documentation/SubmitChecklist when testing your code ***
--
To unsubscribe from this list: send the line "unsubscribe linux-kernel" in
the body of a message to majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html
Please read the FAQ at  http://www.tux.org/lkml/