Return-Path: Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1751436AbbHALWP (ORCPT ); Sat, 1 Aug 2015 07:22:15 -0400 Received: from tex.lwn.net ([70.33.254.29]:41399 "EHLO vena.lwn.net" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1750888AbbHALWN (ORCPT ); Sat, 1 Aug 2015 07:22:13 -0400 Date: Sat, 1 Aug 2015 13:22:10 +0200 From: Jonathan Corbet 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 Subject: Re: [PATCH] scripts/kernel-doc Allow struct arguments documentation in struct body Message-ID: <20150801132210.2c0b84f1@lwn.net> In-Reply-To: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> References: <1438376805-8964-1-git-send-email-danilo.cesar@collabora.co.uk> Organization: LWN.net X-Mailer: Claws Mail 3.11.1 (GTK+ 2.24.28; x86_64-redhat-linux-gnu) MIME-Version: 1.0 Content-Type: text/plain; charset=US-ASCII Content-Transfer-Encoding: 8bit Sender: linux-kernel-owner@vger.kernel.org List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Content-Length: 1004 Lines: 26 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 -- 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/