Messages in this thread | ![/](/images/icornerl.gif) | | Date | Wed, 19 Aug 2009 18:28:56 -0400 (EDT) | From | Alan Stern <> | Subject | Re: [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
| ![\](/images/icornerr.gif) |