Received: by 2002:ac0:a5a7:0:0:0:0:0 with SMTP id m36-v6csp5325802imm; Tue, 21 Aug 2018 09:48:42 -0700 (PDT) X-Google-Smtp-Source: AA+uWPw8Pj0d+vS7m4P98c2IuqSlH8CsyFTVLDHPBv+M/WsC0yDiJJQqOdfGz8PzMGg7fcMcUSGV X-Received: by 2002:a63:d613:: with SMTP id q19-v6mr48013115pgg.327.1534870122367; Tue, 21 Aug 2018 09:48:42 -0700 (PDT) ARC-Seal: i=1; a=rsa-sha256; t=1534870122; cv=none; d=google.com; s=arc-20160816; b=XYK/RHnjq8kyMbKa2FIGOj9LTDHhhzUL4P1d/nqHT1PKeWfoxqpSpzxQgN0xfTDZ8m Q5TdLJ400PjHCGIltZPfHPByWWpP6ShFrCEFiahuoe1lkEXrtNR9TCmascq2CKLwb8HG Ez5KJXf8adEDHpoEgjTBhtIG5zianaqoHkz93Xaw5v3KM7teIEKFmvvFNg31XiydTK2d s2SnRo7O/X/h5xRDduajGIZMCbApq0rR7MSFE1ILAFKjWB9h0phm28id+NQmh/uFItKd ro7PSpPZS6VrkbeEfGniHf+sJi1Fo2IGVheoSpaIckDXvlO5BOg+DrfFMjUN8PrdjsC4 Y6sw== ARC-Message-Signature: i=1; a=rsa-sha256; c=relaxed/relaxed; d=google.com; s=arc-20160816; h=list-id:precedence:sender:user-agent:in-reply-to :content-disposition:mime-version:references:message-id:subject:cc :to:from:date:arc-authentication-results; bh=dw7GH6LI2i0s+TXLt6GPh/JTC3EuRHzAdYQlJpuux+o=; b=Foi6k4/1Lds5b5yhgRdCVDfI+flyjVixdlOsKCUuKk2BclniuV0wOb12ClN852rRHQ hvUBbl8DZ6t5IVx0BNtuhltFOAdAvNnpZ9MUBg+E8aRouy1oHqxFoZ9a3QAB8XLRs6xC kN0a48YJUdh3OqTsNJoIlYxVSHyErap8fSQGX3V1/groh8OFjDjQa7sMBT/niCiuKn2q DxSadzF1M1JAc1V4+IhpkFh7q7c7/f8sO4npR1aRG7Z8BTRcAfTGNMI9PE6sGqZy2LMq vQkEWemrMbSIM+nlfj21vjwXOOeN6E1eJwnDeK391LzyKgjDrMgVS6rSOiY7Nqb0ORn/ zjHw== ARC-Authentication-Results: i=1; mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Return-Path: Received: from vger.kernel.org (vger.kernel.org. [209.132.180.67]) by mx.google.com with ESMTP id h2-v6si2167305plh.145.2018.08.21.09.48.27; Tue, 21 Aug 2018 09:48:42 -0700 (PDT) Received-SPF: pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) client-ip=209.132.180.67; Authentication-Results: mx.google.com; spf=pass (google.com: best guess record for domain of linux-kernel-owner@vger.kernel.org designates 209.132.180.67 as permitted sender) smtp.mailfrom=linux-kernel-owner@vger.kernel.org Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1727546AbeHUUFR (ORCPT + 99 others); Tue, 21 Aug 2018 16:05:17 -0400 Received: from usa-sjc-mx-foss1.foss.arm.com ([217.140.101.70]:52034 "EHLO foss.arm.com" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1727043AbeHUUFR (ORCPT ); Tue, 21 Aug 2018 16:05:17 -0400 Received: from usa-sjc-imap-foss1.foss.arm.com (unknown [10.72.51.249]) by usa-sjc-mx-foss1.foss.arm.com (Postfix) with ESMTP id 32B66ED1; Tue, 21 Aug 2018 09:44:25 -0700 (PDT) Received: from e107564-lin.cambridge.arm.com (e107564-lin.cambridge.arm.com [10.2.131.9]) by usa-sjc-imap-foss1.foss.arm.com (Postfix) with ESMTPSA id F236D3F5BC; Tue, 21 Aug 2018 09:44:22 -0700 (PDT) Date: Tue, 21 Aug 2018 17:44:17 +0100 From: Brian Starkey To: Matthew Wilcox Cc: dri-devel@lists.freedesktop.org, daniel.vetter@ffwll.ch, airlied@linux.ie, gustavo@padovan.org, maarten.lankhorst@linux.intel.com, seanpaul@chromium.org, corbet@lwn.net, linux-doc@vger.kernel.org, linux-kernel@vger.kernel.org, alexandru-cosmin.gheorghe@arm.com, liviu.dudau@arm.com, ayan.halder@arm.com Subject: Re: [PATCH] drm/fourcc: Add DOC: overview comment Message-ID: <20180821164416.GA11553@e107564-lin.cambridge.arm.com> References: <20180821161611.10424-1-brian.starkey@arm.com> <20180821162639.GA21697@bombadil.infradead.org> MIME-Version: 1.0 Content-Type: text/plain; charset=us-ascii; format=flowed Content-Disposition: inline In-Reply-To: <20180821162639.GA21697@bombadil.infradead.org> User-Agent: Mutt/1.5.21 (2010-09-15) Sender: linux-kernel-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: linux-kernel@vger.kernel.org Hi Matthew, On Tue, Aug 21, 2018 at 09:26:39AM -0700, Matthew Wilcox wrote: >On Tue, Aug 21, 2018 at 05:16:11PM +0100, Brian Starkey wrote: >> There's a number of things which haven't previously been documented >> around the usage of format modifiers. Capture the current >> understanding in an overview comment and add it to the rst >> documentation. >> >> Ideally, the generated documentation would also include documentation >> of all of the #defines, but the kernel-doc system doesn't currently >> support kernel-doc comments on #define constants. > >Can you turn them into enums? This seems to work ok: > >-/* color index */ >-#define DRM_FORMAT_C8 fourcc_code('C', '8', ' ', ' ') /* [7:0] C */ >- >-/* 8 bpp Red */ >-#define DRM_FORMAT_R8 fourcc_code('R', '8', ' ', ' ') /* [7:0] R */ >+enum { >+ /* color index */ >+ DRM_FORMAT_C8 = fourcc_code('C', '8', ' ', ' '), /* [7:0] C */ >+ /* 8 bpp Red */ >+ DRM_FORMAT_R8 = fourcc_code('R', '8', ' ', ' '), /* [7:0] R */ >+}; > >but I appreciate this is user API and maybe there's some code out there >that does #ifndef DRM_FORMAT_C8 ... Thanks for the suggestion, Daniel did mention the same. However, unfortunately I don't think we can safely change the UAPI header in this manner. Cheers, -Brian