From: Randy Dunlap <rdunlap@xenotime.net>
To: james_p_freyensee@linux.intel.com
Cc: gregkh@suse.de, linux-kernel@vger.kernel.org,
suhail.ahmed@intel.com, christophe.guerard@intel.com
Subject: Re: [PATCH 3/4] Intel PTI implementaiton of MIPI 1149.7.
Date: Thu, 21 Apr 2011 14:17:54 -0700 [thread overview]
Message-ID: <20110421141754.bfc8eb00.rdunlap@xenotime.net> (raw)
In-Reply-To: <1303419999.13457.107.camel@localhost>
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@linux.intel.com 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 ***
next prev parent reply other threads:[~2011-04-21 21:17 UTC|newest]
Thread overview: 19+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-04-19 22:58 james_p_freyensee
2011-04-19 23:15 ` Randy Dunlap
2011-04-20 23:05 ` J Freyensee
2011-04-20 23:10 ` Randy Dunlap
2011-04-21 21:06 ` J Freyensee
2011-04-21 21:17 ` Randy Dunlap [this message]
2011-04-20 1:25 ` David Rientjes
2011-04-20 9:46 ` Alan Cox
2011-04-20 18:07 ` J Freyensee
2011-04-22 17:57 ` J Freyensee
2011-04-22 23:32 james_p_freyensee
2011-04-24 0:55 ` Jesper Juhl
2011-04-24 1:08 ` Jesper Juhl
2011-05-05 17:06 ` J Freyensee
2011-05-05 20:37 ` Jesper Juhl
2011-05-05 17:27 ` J Freyensee
2011-05-05 20:42 ` Jesper Juhl
2011-05-05 22:30 ` J Freyensee
2011-05-06 23:56 james_p_freyensee
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20110421141754.bfc8eb00.rdunlap@xenotime.net \
--to=rdunlap@xenotime.net \
--cc=christophe.guerard@intel.com \
--cc=gregkh@suse.de \
--cc=james_p_freyensee@linux.intel.com \
--cc=linux-kernel@vger.kernel.org \
--cc=suhail.ahmed@intel.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox
all inboxes | Powered by JetHome®