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: <20220912184756.61492ad1@coco.lan>
Date:   Mon, 12 Sep 2022 18:47:56 +0200
From:   Mauro Carvalho Chehab <mchehab@...nel.org>
To:     Matt Roper <matthew.d.roper@...el.com>
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

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.

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