pci kernel-doc fatal error
PATCH 1/1 pci kernel-doc fatal error
From: Randy Dunlap <[email protected]>
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'
--- drivers/pci/pci.c | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-)
drivers/pci/pci.c +2 -4
@@ -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.
Quoted 7 lines · Randy Dunlap
From: Randy Dunlap <[email protected]>
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 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.
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 ;)
Quoted 22 lines
drivers/pci/pci.c +2
-4@@ -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.
Signature · 8 lines
Michael Ellerman OzLabs, IBM Australia Development Lab wwweb: http://michael.ellerman.id.au phone: +61 2 6212 1183 (tie line 70 21183) We do not inherit the earth from our ancestors, we borrow it from our children. - S.M.A.R.T Person
Quoted 10 lines · On Tue, 22 Jul 2008 09:07:45 +1000 Michael Ellerman wrote:
Quoted 7 lines · Randy Dunlap
From: Randy Dunlap <[email protected]>
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...
Quoted 5 lines
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.
Quoted 5 lines
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.
Quoted 15 lines
Quoted 15 lines
drivers/pci/pci.c +1
-2@@ -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 }
Quoted 7 lines
drivers/pci/pci.c int pci_prepare_to_sleep(struct pci_dev · line 1186
Quoted 7 lines
drivers/pci/pci.c +1
-2/** -* 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/
Quoted 11 lines · Randy Dunlap
Quoted 9 lines · On Tue, 22 Jul 2008 09:07:45 +1000 Michael Ellerman wrote:
Quoted 7 lines · Randy Dunlap
From: Randy Dunlap <[email protected]>
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'
Quoted 7 lines
Quoted 1 line
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...
Sure.
Quoted 7 lines
Quoted 3 lines
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.
I guess there's also a good reason why the kernel implements its own doco-from-c-comments extraction tool, rather than using something that already exists (doxygen?).
cheers
Signature · 8 lines
Michael Ellerman OzLabs, IBM Australia Development Lab wwweb: http://michael.ellerman.id.au phone: +61 2 6212 1183 (tie line 70 21183) We do not inherit the earth from our ancestors, we borrow it from our children. - S.M.A.R.T Person
--- Original Message ---
Quoted 26 lines · Randy Dunlap
Quoted 11 lines · On Tue, 22 Jul 2008 09:07:45 +1000 Michael Ellerman wrote:
Quoted 10 lines · Randy Dunlap
Quoted 7 lines
From: Randy Dunlap <[email protected]>
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'
Quoted 7 lines
Quoted 1 line
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...
Sure.
Quoted 4 lines
Quoted 3 lines
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 ;)
Quoted 8 lines
Quoted 3 lines
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.I guess there's also a good reason why the kernel implements its own
doco-from-c-comments extraction tool, rather than using something that already exists (doxygen?).
I don't know the history behind it. I.e., it happened before I began caring about it.
~Randy