[Ksummit-discuss] [CORE-TOPIC] Documentation

[Mauro Carvalho Chehab]

Em Mon, 13 Jul 2015 20:36:47 -0600
Jonathan Corbet <corbet at lwn.net> 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.

Regards,
Mauro