lkml.org 
[lkml]   [2009]   [Aug]   [19]   [last100]   RSS Feed
Views: [wrap][no wrap]   [headers]  [forward] 
 
Messages in this thread
/
Date
From
SubjectRe: [RFC][PATCH 1/7] PM: Update kerneldoc comments in drivers/base/power/main.c
On Wed, 19 Aug 2009, Rafael J. Wysocki wrote:

> On Monday 17 August 2009, Rafael J. Wysocki wrote:
> > From: Rafael J. Wysocki <rjw@sisk.pl>
> > Subject: PM: Update kerneldoc comments in drivers/base/power/main.c
> >
> > The kerneldoc comments in drivers/base/power/main.c are generally
> > outdated and some of them don't describe the functions very
> > accurately. Update them and standardize the format to use spaces
> > instead of tabs.
> >
> > Signed-off-by: Rafael J. Wysocki <rjw@sisk.pl>
>
> Any objections to this patch from anyone? Greg, Alan, Randy?

Just some very minor changes.

> > /**
> > - * pm_op - execute the PM operation appropiate for given PM event
> > - * @dev: Device.
> > - * @ops: PM operations to choose from.
> > - * @state: PM transition of the system being carried out.
> > + * pm_op - Execute the PM operation appropiate for given PM event.
> > + * @dev: Device to handle.
> > + * @ops: PM operations to choose from.
> > + * @state: PM transition of the system being carried out.
> > */

Here and in several places below, "appropriate" is missing an "r".

> > /**
> > - * pm_noirq_op - execute the PM operation appropiate for given PM event
> > - * @dev: Device.
> > - * @ops: PM operations to choose from.
> > - * @state: PM transition of the system being carried out.
> > + * pm_noirq_op - Execute the PM operation appropiate for given PM event.
> > + * @dev: Device to handle.
> > + * @ops: PM operations to choose from.
> > + * @state: PM transition of the system being carried out.
> > *
> > - * The operation is executed with interrupts disabled by the only remaining
> > - * functional CPU in the system.
> > + * The driver of @dev will not receive interrupts while this fuction is being
> > + * executed.
> > */

Here and in several places below, "function" is missing an "n".

> > /**
> > - * dpm_resume - Resume every device.
> > - * @state: PM transition of the system being carried out.
> > + * dpm_resume - Execute "resume" callbacks for non-sysdev devices.
> > + * @state: PM transition of the system being carried out.
> > *
> > - * Execute the appropriate "resume" callback for all devices the status of
> > - * which indicates that they are inactive.
> > + * Execute the appropriate "resume" callback for all devices the status of which
> > + * indicates that they are suspended.
> > */

The phrasing is slightly awkward. "... all devices whose status
indicates..." would be better. Below as well.

> > /**
> > - * dpm_resume_end - Restore state of each device in system.
> > - * @state: PM transition of the system being carried out.
> > + * dpm_resume_end - Execute "resume" callbacks and complete system transition.
> > + * @state: PM transition of the system being carried out.
> > *
> > - * Resume all the devices, unlock them all, and allow new
> > - * devices to be registered once again.
> > + * Resume all the devices, unlock them all, and complete the PM transition of
> > + * the system.
> > */

The "unlock them all" part is a fossil. It should be removed.

Alan Stern



\
 
 \ /
  Last update: 2009-08-20 00:31    [W:0.097 / U:0.084 seconds]
©2003-2020 Jasper Spaans|hosted at Digital Ocean and TransIP|Read the blog|Advertise on this site