From mboxrd@z Thu Jan 1 00:00:00 1970 From: Jonathan Corbet Subject: Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body Date: Sat, 1 Aug 2015 13:22:10 +0200 Message-ID: <20150801132210.2c0b84f1@lwn.net> References: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> Mime-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8bit Return-path: In-Reply-To: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> Sender: linux-doc-owner@vger.kernel.org To: Danilo Cesar Lemes de Paula Cc: 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 List-Id: intel-gfx@lists.freedesktop.org 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? 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. Thanks, jon