Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1752575AbbHCIX0 (ORCPT ); Mon, 3 Aug 2015 04:23:26 -0400 Received: from mail-wi0-f180.google.com ([209.85.212.180]:36885 "EHLO mail-wi0-f180.google.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1751756AbbHCIXX (ORCPT ); Mon, 3 Aug 2015 04:23:23 -0400 Date: Mon, 3 Aug 2015 10:23:19 +0200 From: Daniel Vetter To: Jonathan Corbet Cc: Danilo Cesar Lemes de Paula , linux-doc@vger.kernel.org, Randy Dunlap , Daniel Vetter , Laurent Pinchart , Herbert Xu , Stephan Mueller , Michal Marek , linux-kernel@vger.kernel.org, intel-gfx , dri-devel Subject: Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body Message-ID: <20150803082319.GB24689@phenom.ffwll.local> Mail-Followup-To: Jonathan Corbet , Danilo Cesar Lemes de Paula , linux-doc@vger.kernel.org, Randy Dunlap , Laurent Pinchart , Herbert Xu , Stephan Mueller , Michal Marek , linux-kernel@vger.kernel.org, intel-gfx , dri-devel References: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> <20150801132210.2c0b84f1@lwn.net> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii Content-Disposition: inline In-Reply-To: <20150801132210.2c0b84f1@lwn.net> X-Operating-System: Linux phenom 4.2.0-rc1+ User-Agent: Mutt/1.5.23 (2014-03-12) Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 2626 Lines: 59 On Sat, Aug 01, 2015 at 01:22:10PM +0200, Jonathan Corbet wrote: > On Fri, 31 Jul 2015 18:06:45 -0300 > Danilo Cesar Lemes de Paula wrote: > > > Describing arguments at top of a struct definition works fine > > for small/medium size structs, but it definitely doesn't work well > > for struct with a huge list of elements. > > > > Keeping the arguments list inside the struct body makes it easier > > to maintain the documentation. > > Interesting approach. I think it could make sense, but I fear pushback > from a subset of maintainers refusing to accept this mode. I wonder what > it would take to get a consensus on allowing these in-struct comments? At least in drm we have a lot of such comments (as non-kerneldoc) right above struct members to explain some details. Common examples are: - locks, with a description of what they protect and maybe also how they nest. - vfunc ops structs, with a per-function description of what each hook does. - tricky stuff which can't be described in one sentence only. So it's not just huge structs by number of members, but huge by number of comment lines. Trying to stuff that all into the top kerneldoc comment means that it's much harder to jump to the right comment, and it's also easier to ignore the comments (since it e.g. won't show up in the diff context). The current approach at least in drm is to duplicate comments and that just results in inconsistency. > I'm wondering if we need a kernel summit session on commenting > conventions, markdown-in-kerneldoc, etc? Maybe I'll stick a proposal out > there. Might be useful, but I'm not sure how many people really would actively work on improving the tooling. The only comment I've seen is to maybe use gtkdoc, but that would be a pain since it's slightly incompatible with kerneldoc. And it's the improved tooling I really need for my long-term plan to get solid docs for drm & drm/i915. Next step is to start building a proper doc writer team to make all the bits we already have into a consistent hole (and nag developers to fill in the areas still undocumented). For that I've already pulled Danilo's patches into the drm-intel integration tree and I plan to use them for any further drm kerneldoc I write since we really need them. Thanks, Daniel -- Daniel Vetter Software Engineer, Intel Corporation http://blog.ffwll.ch -- To unsubscribe from this list: send the line "unsubscribe linux-kernel" in the body of a message to majordomo@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html Please read the FAQ at http://www.tux.org/lkml/