How to contribute to kernel documentation

Posted Jan 24, 2020 2:52 UTC (Fri) by willy (subscriber, #9762)
Parent article: How to contribute to kernel documentation

You have to be so careful when volunteering to document a subsystem. I started documenting the radix tree API and got so disgusted with what I was writing that I wrote a replacement API instead.

How to contribute to kernel documentation

Posted Jan 24, 2020 8:35 UTC (Fri) by blackwood (guest, #44174) [Link]

Matches my experience trying to document all the things in drivers/gpu. You always end up with a massive patch series to clean up all the big and little warts, plus then often a few new todo entries encouraging people to move over to more modern helper functions. And finally a relatively small patch to document what's left in terms of functions and data structures ....

How to contribute to kernel documentation

Posted Jan 24, 2020 10:13 UTC (Fri) by neilbrown (subscriber, #359) [Link] (1 responses)

Clearly this article is a thinly disguised attempt to trick developers into improving common code.

How to contribute to kernel documentation

Posted Jan 24, 2020 12:10 UTC (Fri) by unixbhaskar (guest, #44758) [Link]

That's not a bad ploy Neil...ha ha ha ha ha ha it will benefit everyone ...I am sure deep down you are keen ....:)

How to contribute to kernel documentation

Posted Jan 24, 2020 11:44 UTC (Fri) by jani (subscriber, #74547) [Link]

That's one of the great benefit of documenting an API while designing it instead of after the fact. If you can't explain what the API does in reasonably terse plain English, you probably didn't get the API design right.

How to contribute to kernel documentation

Posted Jan 29, 2020 15:06 UTC (Wed) by jwakely (subscriber, #60262) [Link]

Indeed. 18 years ago I started documenting bits of libstdc++:
https://gcc.gnu.org/git/gitweb.cgi?p=gcc.git;h=c0d8816157...

I've now made more than 2500 changes to GCC and I'm still not finished with the docs.