linux-kernel - Re: [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for something else

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite: Windows password security audit tool. GUI, reports in PDF.

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Message-ID: <Yx9qCCmxnSM06CgH@mdroper-desk1.amr.corp.intel.com>
Date:   Mon, 12 Sep 2022 10:19:04 -0700
From:   Matt Roper <matthew.d.roper@...el.com>
To:     Mauro Carvalho Chehab <mchehab@...nel.org>
CC:     Rodrigo Vivi <rodrigo.vivi@...el.com>,
        Ville Syrjälä 
        <ville.syrjala@...ux.intel.com>,
        Alan Previn <alan.previn.teres.alexis@...el.com>,
        Andi Shyti <andi.shyti@...ux.intel.com>,
        Ashutosh Dixit <ashutosh.dixit@...el.com>,
        Chris Wilson <chris@...is-wilson.co.uk>,
        Daniel Vetter <daniel@...ll.ch>,
        Daniele Ceraolo Spurio <daniele.ceraolospurio@...el.com>,
        David Airlie <airlied@...ux.ie>,
        Imre Deak <imre.deak@...el.com>,
        Jani Nikula <jani.nikula@...ux.intel.com>,
        John Harrison <John.C.Harrison@...el.com>,
        Joonas Lahtinen <joonas.lahtinen@...ux.intel.com>,
        Lucas De Marchi <lucas.demarchi@...el.com>,
        Matthew Auld <matthew.auld@...el.com>,
        "Matthew Brost" <matthew.brost@...el.com>,
        Stanislav Lisovskiy <stanislav.lisovskiy@...el.com>,
        Tomas Winkler <tomas.winkler@...el.com>,
        Tvrtko Ursulin <tvrtko.ursulin@...ux.intel.com>,
        Umesh Nerlige Ramappa <umesh.nerlige.ramappa@...el.com>,
        <dri-devel@...ts.freedesktop.org>,
        <intel-gfx@...ts.freedesktop.org>, <linux-kernel@...r.kernel.org>
Subject: Re: [PATCH v3 19/37] drm/i915: stop using kernel-doc markups for
 something else

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@...el.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