[Ksummit-discuss] [CORE-TOPIC] Documentation

[Jonathan Corbet]

On Mon, 13 Jul 2015 21:46:46 +0200
Peter Hüwe <PeterHuewe at gmx.de> wrote:

> > kerneldoc does work, after a fashion.  It works well enough that people
> > use it, and I hear about it quickly when somebody's comment change breaks
> > the docs build.  I don't think we can remove it in the absence of
> > something better.  
> Jonathan, do you keep an up-to-date copy of the generated files somewhere?
> (I cannot get it to work out of the box on my machine)

I don't, sorry.  That would probably be a good thing for me to do for a
number of reasons.

> > Creating "something better" is actually on my list of things to do.  The
> > only problem is that I've had to buy a second 4TB drive to hold that list,
> > so I don't know when I'll have time to think about it.  
> Where do you think are the major issues from your point of view? 

Well, as mentioned before, kerneldoc is fragile.  A little while back
somebody changed a struct to a union without updating the comments to
match; that was enough to break the entire document build process.  That
kind of thing happens a lot; I don't think it should have to be that way.

Beyond that, DocBook is a major pain.  I get a fair number of patches
along the lines of "that </para> should really have been ahead of that
</whatever>".  It's verbose, intimidating to newcomers, and causes more
worn-out shift keys than anything else.  We don't need something with the
complexity of DocBook; something closer to Markdown or ReST would do us
just fine and make the documentation much more accessible.

But making any such change is a big job, and convincing the community to
go with a change in tooling is probably a bigger job.  So I'm not rushing
into it.

> Would doxygen be "something better"? The kernel-doc style looks already quite 
> similar.
> Maybe the kernel should not reinvent everything :)

Doxygen may be worth a look.  I'm personally fond of Sphinx, though I
still haven't done a big project in it.

But this is all just dreaming until somebody has the time to do a major
docs overhaul and sell it to everybody else.  Until then, I'm focused on
slowly improving what we have now...

jon