Received-SPF: pass (google.com: domain of linux-kernel-owner@vger.kernel.org designates 2620:137:e000::1:20 as permitted sender) client-ip=2620:137:e000::1:20;
Date:   Mon, 12 Sep 2022 10:19:04 -0700
From:   Matt Roper <matthew.d.roper@intel.com>
To:     Mauro Carvalho Chehab <mchehab@kernel.org>
CC:     Rodrigo Vivi <rodrigo.vivi@intel.com>,
        Ville =?iso-8859-1?Q?Syrj=E4l=E4?= 
        <ville.syrjala@linux.intel.com>,
        Alan Previn <alan.previn.teres.alexis@intel.com>,
        Andi Shyti <andi.shyti@linux.intel.com>,
        Ashutosh Dixit <ashutosh.dixit@intel.com>,
        Chris Wilson <chris@chris-wilson.co.uk>,
        Daniel Vetter <daniel@ffwll.ch>,
        Daniele Ceraolo Spurio <daniele.ceraolospurio@intel.com>,
        David Airlie <airlied@linux.ie>,
        Imre Deak <imre.deak@intel.com>,
        Jani Nikula <jani.nikula@linux.intel.com>,
        John Harrison <John.C.Harrison@intel.com>,
        Joonas Lahtinen <joonas.lahtinen@linux.intel.com>,
        Lucas De Marchi <lucas.demarchi@intel.com>,
        Matthew Auld <matthew.auld@intel.com>,
        "Matthew Brost" <matthew.brost@intel.com>,
        Stanislav Lisovskiy <stanislav.lisovskiy@intel.com>,
        Tomas Winkler <tomas.winkler@intel.com>,
        Tvrtko Ursulin <tvrtko.ursulin@linux.intel.com>,
        Umesh Nerlige Ramappa <umesh.nerlige.ramappa@intel.com>,
        <dri-devel@lists.freedesktop.org>,
        <intel-gfx@lists.freedesktop.org>, <linux-kernel@vger.kernel.org>
Subject: Re: [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for
 something else
Message-ID: <Yx9qCCmxnSM06CgH@mdroper-desk1.amr.corp.intel.com>
References: <cover.1662708705.git.mchehab@kernel.org>
 <6405f00c4ba03987abf7635f4c62d86b40a0e521.1662708705.git.mchehab@kernel.org>
 <Yx9LxciaH/y8fnRD@mdroper-desk1.amr.corp.intel.com>
 <20220912184756.61492ad1@coco.lan>
Content-Type: text/plain; charset="us-ascii"
Content-Disposition: inline
In-Reply-To: <20220912184756.61492ad1@coco.lan>
MIME-Version: 1.0
X-MS-Exchange-AntiSpam-MessageData-ChunkCount: 1
X-MS-Exchange-AntiSpam-MessageData-0: =?us-ascii?Q?wCogdo0EZpV7p+kwaxMkMv3VqzTyN1d4xWyBIC9kZFfh4KWLXculjPhUAZXX?=
 =?us-ascii?Q?1So6ZcA2gUkSKQOSkmKY+nGvoYykjYdbTnUtUfQhd/pZ5GQwEM7a+Uqrvrpx?=
 =?us-ascii?Q?Cj6m2JI0s5w7Ag3H0fOI633cK98bdKikuQooWpZpeeHfu+0FwJqBsiVzrXT+?=
 =?us-ascii?Q?H7tpXS4BblqEmh22r4WBDn0MT1xxvC2CWOAIRWU/jFaEpcFNYhuopaTaYKWU?=
 =?us-ascii?Q?9GUp9bfubfy7fSOqRavWpnKiyM0sckgFQjtD+kHCkJAvPtodSZZ2HheSTgRA?=
 =?us-ascii?Q?6qapfDUbpZVLUSxAMcZ4JnqtnWyrTeDgpy+edT1Tc5RKC2xSlNRtOTRS1+4F?=
 =?us-ascii?Q?I2QiGJj5yHbUIBeG5paW+OwODmcPkFY3XkcC8Q1YzRVJT8xbBZYNLYvtV6fs?=
 =?us-ascii?Q?IzoSnUMRYfIGOW5jlbvg51WhrrUzSpcnL3IRDcWI0Cj1Ak6lEomlDMCk4KAN?=
 =?us-ascii?Q?fotN5FPMOT3bfL7vJ20YD0CPDdYgd7d2q2VCnl1BhISltngaFnj+Zmidx4iv?=
 =?us-ascii?Q?0/lnYakeuKy0o/7GzgoY5vEHTvUfxo8ZYAlyv5JnzQqVcLC69V0EihtWr3pE?=
 =?us-ascii?Q?yoOBQ0TJLsZiYvFQpa3StscWoUAQPAAYzBtNIsg22UoYcAaFU4Glikm5FLoZ?=
 =?us-ascii?Q?pnf4v8ufKeaQBP6b5e6mFevhWk1thw1QHfTrwSCY5wUvB+dYrNDIjaG9fiU8?=
 =?us-ascii?Q?vlXe3umMWROdmXSQ3duzpqKrzvnutkhxV5zDKmbOMo7rtfaoHNLOTIUzd3ro?=
 =?us-ascii?Q?Lcev3MZ6auLYMXst5pQjyDK4OMkMyNOm4Gn+J/E1jteDWnY4JXo11ldRrJYT?=
 =?us-ascii?Q?GRL7UWKrv6+HLW59jEBdPrn3sZkKNlmTXqIv0QJbQ2+KeyS2R4Sv7N+WklRE?=
 =?us-ascii?Q?MZJiuJCvOEyb1xY6QD9BnN024QEcNF/5LY1W5y5mruMnrh36kAWp3yYJPJ9O?=
 =?us-ascii?Q?aR+sMCKfIrLNnnlzyzxEJkYkMCeVUxIsBfVq6G1FSu6rM2DtPTbpaXxJOQAC?=
 =?us-ascii?Q?s5QF/xVyD3NU0Cmwjf6WY3iEH5jNro6cwRrU0SdS3ZMlY182HUK3I64S3mSa?=
 =?us-ascii?Q?q5dGFgDzTP5BiuYVAJJwIVsLRLP0EhNZUEzwS175Ua7ajrdmlvJxKkOFakYn?=
 =?us-ascii?Q?I/9GQnqMBCWzRUPpueHuYfqRR3jfUaDSmzrnXsMpt2mDRdZVjzY2b9TjbB2Y?=
 =?us-ascii?Q?+21ROCzv+FIg0qFikmSYO5KzeKjazREDew66Kn+UAqa+BX73q+qtXqpJyZdq?=
 =?us-ascii?Q?3RtyZEJDgpqTdZo93MK+kUjW8aTxa4HoEkTT8YnEtAFXRT92wV01KSnl9YTA?=
 =?us-ascii?Q?9FGGheKSYjL7yLaVVn8sKBywn21s2wFQf9GvSNbp+FZ2Ro9a9TPd6BIWNalz?=
 =?us-ascii?Q?+p8vESbgZ2CG0XiiCtRaQpbkNwz6ngZ7M9NUb6RvHDdf31Ko/YPFb2oq1kbu?=
 =?us-ascii?Q?1nS+aWa8QWjalrlmQR592u1jPu9WhUyeqUrVCC6oWu8JXRxr0h6CQHpWy8EM?=
 =?us-ascii?Q?yn9LpFuD1Oem5gXP8OTYUJe2BskPndMR/HV7TSfP2J7Jd+xsJQpDgpYFLAL2?=
 =?us-ascii?Q?IEGu/LGSxzLd0osl+YMxc54h7Z+/C3pN30jhsQzSE24YhFbE2xlMIZJz8F3S?=
 =?us-ascii?Q?FA=3D=3D?=
X-MS-Exchange-CrossTenant-Network-Message-Id: 77a06d1a-5efb-43ca-390d-08da94e2e673
X-MS-Exchange-CrossTenant-AuthSource: MWHPR11MB1632.namprd11.prod.outlook.com
X-MS-Exchange-CrossTenant-AuthAs: Internal
X-MS-Exchange-CrossTenant-OriginalArrivalTime: 12 Sep 2022 17:19:07.8833
 (UTC)
X-MS-Exchange-CrossTenant-FromEntityHeader: Hosted
X-MS-Exchange-CrossTenant-Id: 46c98d88-e344-4ed4-8496-4ed7712e255d
X-MS-Exchange-CrossTenant-MailboxType: HOSTED
X-MS-Exchange-CrossTenant-UserPrincipalName: ZTkb5ExnHK2IaUd1k68WJEuB8pHzuSdUf7nOdrZr/uUOx/eQSC0NqUUAnXdvYShyex2k+oUFrhfAhICOyXE08+wk9YvxZUGm4V+uKhd/bW8=
X-MS-Exchange-Transport-CrossTenantHeadersStamped: BL3PR11MB6434
X-OriginatorOrg: intel.com
X-Spam-Status: No, score=-7.1 required=5.0 tests=BAYES_00,DKIMWL_WL_HIGH,
        DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,DKIM_VALID_EF,RCVD_IN_DNSWL_HI,
        SPF_HELO_NONE,SPF_NONE,T_SCC_BODY_TEXT_LINE autolearn=ham
        autolearn_force=no version=3.4.6
X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on
        lindbergh.monkeyblade.net
Precedence: bulk
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org

On Mon, Sep 12, 2022 at 06:47:56PM +0200, Mauro Carvalho Chehab wrote:
> Hi Matt,
> 
> Em Mon, 12 Sep 2022 08:09:57 -0700
> Matt Roper <matthew.d.roper@intel.com> escreveu:
> 
> > > --- a/drivers/gpu/drm/i915/gt/intel_context_types.h
> > > +++ b/drivers/gpu/drm/i915/gt/intel_context_types.h  
> > 
> > Several of the comments in this file do appear to be kerneldoc (in fact
> > kerneldoc that was specifically requested during code review at
> > https://patchwork.freedesktop.org/patch/448456/#comment_804252) and this
> > file is included from Documentation/gpu/i915.rst, so I think some of
> > these changes might be moving in the wrong direction.  Should we instead
> > focus on fixing up the comments that aren't quite formatted properly?
> 
> Those *appear* to be kernel-doc markups, but they aren't, because
> the structs themselves are not properly marked. See, for instance
> struct intel_context.
> 
> scripts/kerneldoc will *only* consider what's there as a proper
> comment if you add:
> 
> 	/**
> 	 * struct intel_context - describes an i915 context
> 	 * <add a proper description for it>
> 	 */
> 	struct intel_context {
> 		union {
> 			/** @ref: a kernel object reference */
> 	                struct kref ref; /* no kref_get_unless_zero()! */
> 			/** @rcu: a rcu header */
> 	                struct rcu_head rcu;
> 	        };
> 		...
> 	}
> 
> Describing all fields inside the struct. Just placing
> 	/** something */
> on some random places in the middle doesn't make it a kernel-doc.

Right, what we have today is incomplete/incorrect.  But I think we
should be fixing that by adding the missing documentation on the
structure, rather than giving up and removing the kerneldoc.  The end
goal should be to have proper generated documentation, not just silence
the warnings while leaving the actual output incomplete.


Matt

> 
> If you actually run kernel-doc in Werror mode:
> 
> 	./scripts/kernel-doc -Werror -sphinx-version 2.4.4 drivers/gpu/drm/i915/gt/intel_context_types.h | echo "ERROR!"
> 	ERROR!
> 	drivers/gpu/drm/i915/gt/intel_context_types.h:1: warning: no structured comments found
> 	1 warnings as Errors
> 
> you'll see that this is currently broken.
> 
> Thanks,
> Mauro

-- 
Matt Roper
Graphics Software Engineer
VTT-OSGC Platform Enablement
Intel Corporation