From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp1.linuxfoundation.org (smtp1.linux-foundation.org [172.17.192.35]) by mail.linuxfoundation.org (Postfix) with ESMTPS id A65BEBB6 for ; Tue, 14 Jul 2015 13:57:19 +0000 (UTC) Received: from galahad.ideasonboard.com (galahad.ideasonboard.com [185.26.127.97]) by smtp1.linuxfoundation.org (Postfix) with ESMTPS id 2C2ED160 for ; Tue, 14 Jul 2015 13:57:19 +0000 (UTC) From: Laurent Pinchart To: ksummit-discuss@lists.linuxfoundation.org Date: Tue, 14 Jul 2015 16:57:37 +0300 Message-ID: <49549961.dqTOgxpqna@avalon> In-Reply-To: <20150714094342.36be30fe@recife.lan> References: <201507130038.01474.PeterHuewe@gmx.de> <20150713203647.1fdb8bb4@lwn.net> <20150714094342.36be30fe@recife.lan> MIME-Version: 1.0 Content-Transfer-Encoding: 7Bit Content-Type: text/plain; charset="us-ascii" Cc: Dan Carpenter , Mauro Carvalho Chehab Subject: Re: [Ksummit-discuss] [CORE-TOPIC] Documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , 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