Re: [PATCH] pci kernel-doc fatal error

[Randy Dunlap <randy.dunlap@oracle.com>]

On Tue, 22 Jul 2008 09:07:45 +1000 Michael Ellerman wrote:

> On Mon, 2008-07-21 at 09:27 -0700, Randy Dunlap wrote:
> > From: Randy Dunlap <randy.dunlap@oracle.com>
> > 
> > Fix kernel-doc comments so that they don't produce errors.
> > Also cut some extraneous copy-paste text.
> > 
> > Error(linhead//drivers/pci/pci.c:1133): duplicate section name 'Description'
> > Error(linhead//drivers/pci/pci.c:1189): duplicate section name 'Description'
> 
> But now the description lines exceed 80 columns, and with longer

Yes, I'm pretty well aware of that.  :(
This is one of the places where we tolerate that, while not enjoying it.

This is a request that akpm has also made, and it makes some sense, and it's
on my long list of (volunteer) doc work to do...

> function names it's even harder to write a meaningful description in
> under 80 columns.

> Couldn't kerneldoc be modified to accept multiline descriptions? I know
> they're /short/ descriptions, but still.

Well, Documentation/kernel-doc-nano-HOWTO.txt explains how to format the
function description and how to handle long(er) descriptions.

> cheers
> 
> ps. I did look at changing kerneldoc to do that myself, but whereas
> previously I thought I didn't really know perl, now I /know/ I totally
> don't know perl ;)

Yes, I understand that comment.  ;)
That's part of the problem, of course.
I.e., if it were straightforward, it would probably already be done.


> > --- linhead.orig/drivers/pci/pci.c
> > +++ linhead/drivers/pci/pci.c
> > @@ -1123,8 +1123,7 @@ int pci_enable_wake(struct pci_dev *dev,
> >  }
> >  
> >  /**
> > - * pci_prepare_to_sleep - prepare PCI device for system-wide transition into
> > - *                        a sleep state
> > + * pci_prepare_to_sleep - prepare PCI device for system-wide transition into a sleep state
> >   * @dev: Device to handle.
> >   *
> >   * Choose the power state appropriate for the device depending on whether
> > @@ -1181,8 +1180,7 @@ int pci_prepare_to_sleep(struct pci_dev
> >  }
> >
> >  /**
> > - * pci_back_from_sleep - turn PCI device on during system-wide transition into
> > - *                       the working state a sleep state
> > + * pci_back_from_sleep - turn PCI device on during system-wide transition into working state
> >   * @dev: Device to handle.
> >   *
> >   * Disable device's sytem wake-up capability and put it into D0.



---
~Randy
Linux Plumbers Conference, 17-19 September 2008, Portland, Oregon USA
http://linuxplumbersconf.org/