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

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

On Tuesday 14 July 2015 09:43:42 Mauro Carvalho Chehab wrote:
> Em Mon, 13 Jul 2015 20:36:47 -0600 Jonathan Corbet escreveu:
> > > Would doxygen be "something better"? The kernel-doc style looks already
> > > quite similar.
> > > Maybe the kernel should not reinvent everything :)
> 
> My experience is that, from time to time, people send us drivers written
> by the manufacturer with Doxygen-compatible tags. Converting them to
> kernel-doc is a huge task, not worthing the effort. I tried in the past
> to request developers to "fix" the comments. The net result is either
> to not have a final version of the driver submitted or to receive a
> comments-stripped version of it, with is actually worse, as we loose
> lots of otherwise good documentation. So, nowadays, I'm opting to keep
> whatever comments are there at the code, provided that it is not using
> C99 comments.
> 
> So, I'm a huge fan of extending the kernel-doc to accept all markup tags
> that Doxygen supports.
> 
> > Doxygen may be worth a look.  I'm personally fond of Sphinx, though I
> > still haven't done a big project in it.
> 
> I never used Sphinx. Doxygen seems better on my eyes, because people
> already sends us media drivers using Doxygen tags style. Also, as
> mentioned, kernel-doc style is a subset. Not to mention that, in the
> specific case of media,we're using Doxygen to document some libraries
> packaged inside v4l-utils (with is the userspace counterpart of the
> Kernel subsystem). So, at least for me, Doxygen would be easier to use.

We certainly need to accept documentation formats that are easy to use and 
write, but let's not forget that the biggest issue (in my opinion) is that we 
often don't get documentation at all. Cumbersome formats and tools might 
explain part of it, but that's not the whole story. How can we ensure that 
documentation gets written, merged and kept up to date ? What kind of 
incentives can we give ? The stick is easy to wave by not merging code changes 
that are not documented, but that can easily backfire.

-- 
Regards,

Laurent Pinchart