Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1757389AbcCCPpt (ORCPT ); Thu, 3 Mar 2016 10:45:49 -0500 Received: from mail-ob0-f179.google.com ([209.85.214.179]:32995 "EHLO mail-ob0-f179.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1755352AbcCCPpr (ORCPT ); Thu, 3 Mar 2016 10:45:47 -0500 MIME-Version: 1.0 X-Originating-IP: [2a02:168:56c9:0:decc:6e78:7e96:b452] In-Reply-To: <20160303081709.5907bcd8@lwn.net> References: <20160213145317.247c63c7@lwn.net> <87y49zr74t.fsf@intel.com> <20160303071305.247e30b1@lwn.net> <20160303143425.2361dea2@lxorguk.ukuu.org.uk> <20160303081709.5907bcd8@lwn.net> Date: Thu, 3 Mar 2016 16:45:45 +0100 Message-ID: Subject: Re: Kernel docs: muddying the waters a bit From: Daniel Vetter To: Jonathan Corbet Cc: One Thousand Gnomes , Jani Nikula , LKML , linux-doc@vger.kernel.org, Keith Packard , Mauro Carvalho Chehab , Hans Verkuil , "linux-media@vger.kernel.org" , Graham Whaley Content-Type: text/plain; charset=UTF-8 Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 1417 Lines: 30 On Thu, Mar 3, 2016 at 4:17 PM, Jonathan Corbet wrote: > I assume you're referring to gtk-doc? It's web page > (http://www.gtk.org/gtk-doc/) starts by noting that it's "a bit awkward to > setup and use"; they recommend looking at Doxygen instead. So I guess I'm > not really sure what it offers that merits throwing another option into > the mix now? What am I missing? We use gtk-doc for the i915 testcase and tooling repo in userspace (intel-gpu-tools). The setup is somewhat arcane (some build-fu that is fumbly, and xml files to tie everything together). But it looks pretty and works well otherwise. It should be at https://01.org/linuxgraphics/gfx-docs/igt/ but our autobuilder seems to be screwed up right now. Of course I considered it as an option, but like doxygen it has it's own strong opinion about how in-code comments should look like, and those differ from kerneldoc syntax. Beyond that I don't really see benefits over any of the solutions proposed here already (either sphinx or rst or horror! even the hackfest I still carry around in drm-intel.git branches). Btw for igt we went with gtkdoc over docygen because a few people on our team had "doxygen only over my corpse" level kind of strong opinions. Everyone just loves their own color choice for this bikeshed ;-) -Daniel -- Daniel Vetter Software Engineer, Intel Corporation +41 (0) 79 365 57 48 - http://blog.ffwll.ch