Skip to contentSkip to conversation

pci kernel-doc fatal error

PATCH In review Randy Dunlap 2 participants 5 messages Jul 21, 2008 – Jul 22, 2008 PCI

lore
Share & tools
lore
#0 lore raw

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.
#1 lore raw
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
#2 lore raw
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/

#3 lore raw
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
#4 lore raw

--- 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