Re: [Ksummit-discuss] [CORE-TOPIC] Documentation

[Laurent Pinchart <laurent.pinchart@ideasonboard.com>]

(CC'ing Daniel Vetter)

On Monday 13 July 2015 20:36:47 Jonathan Corbet wrote:
> On Mon, 13 Jul 2015 21:46:46 +0200 Peter Hüwe 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...

Daniel, I think I recall you mentioning some efforts going in that direction. 
Any update ?

-- 
Regards,

Laurent Pinchart