On Thu, 17 Feb 2000, Alan Cox wrote:
> Docs are important. Very important. There are now some passable books on the
> Linux kernel although the rather nice device driver writing book is still
> due its much needed update.
Is there any news about the update to the Rubini's Linux device drivers
book? I understood someone else is updating it but would that cover 2.2
and/or 2.4 and when will it be published?
> BTW, if you look at 2.3.45 and friends you'll notice one or two files now
> using gdoc so that you can generate function references directly from the
> drivers.
Oh, that is gdoc syntax? I looked for gdoc on GNOME CVS and found a perl
script and patch to c2man. From the c2man documentation I got the
impression that it had a different view to the document generation than
the doc++ based tools (such as kdoc etc.). That is it didn't use tags and
/** */ style comments. But maybe I got some ancient version (it was dated
1998 something)?
My main gripe in doc++ (apart from needing LaTeX stuff such as preceding
backslash to any underscore) is the 'aesthetically' ugly way to document
structure fields (call me loony but it hurts my eyes, really):
/**
* blah.
*/
struct foobar
{
/** description 1 */
int field1;
/** description 2 */
int field2;
};
I'd rather see it done like this:
/**
* blah
*
* @field1 description 1
* @field2 description 2
*/
struct foobar
{
int field1;
int field2;
};
But enough of this. I'd like to know if there is a more general consensus
about the kernel needing an automatic documentation system. Or is this old
news and there's already such an effort going on?
If not then maybe there should be discussion concerning tools,
possible modifications needed to suit our purposes, policy issues and
such.
-- D.- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.rutgers.edu Please read the FAQ at http://www.tux.org/lkml/
This archive was generated by hypermail 2b29 : Wed Feb 23 2000 - 21:00:18 EST