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 D0713B3D for ; Tue, 14 Jul 2015 12:43:48 +0000 (UTC) Received: from lists.s-osg.org (lists.s-osg.org [54.187.51.154]) by smtp1.linuxfoundation.org (Postfix) with ESMTP id 7E6671BF for ; Tue, 14 Jul 2015 12:43:47 +0000 (UTC) Date: Tue, 14 Jul 2015 09:43:42 -0300 From: Mauro Carvalho Chehab To: Jonathan Corbet Message-ID: <20150714094342.36be30fe@recife.lan> In-Reply-To: <20150713203647.1fdb8bb4@lwn.net> References: <201507130038.01474.PeterHuewe@gmx.de> <20150713114509.14f1f866@lwn.net> <201507132146.47186.PeterHuewe@gmx.de> <20150713203647.1fdb8bb4@lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 7bit Cc: Dan Carpenter , ksummit-discuss@lists.linuxfoundation.org Subject: Re: [Ksummit-discuss] [CORE-TOPIC] Documentation List-Id: List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , 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. Regards, Mauro