Re: [PATCH 2/2] drm: ensure drm headers are self-contained and pass kernel-doc

[Jani Nikula <jani.nikula@intel.com>]

On Mon, 03 Mar 2025, Masahiro Yamada <masahiroy@kernel.org> wrote:
> On Mon, Mar 3, 2025 at 7:02 PM Jani Nikula <jani.nikula@intel.com> wrote:
>>
>> On Mon, 03 Mar 2025, Masahiro Yamada <masahiroy@kernel.org> wrote:
>> And one of the underlying goals is to make for minimal headers with
>> minimal includes and minimal dependencies, preferring forward
>> declarations over includes, splitting functionality by header, etc. It's
>> just that doing that often leads to broken headers, unless you actually
>> build test them... and here we are.
>
>
> What I learned from my last attempt is that we cannot avoid
> false positives without adding a lot of exceptions.

All of the drm core, xe and i915 headers build fine without
exceptions. There are no false positives. (*)

> We can never be certain whether you are making DRM headers
> self-contained for valid reasons or for hypothetical, invalid ones.

Please enlighten me. What are hypothetical, invalid reasons for making
headers self-contained?

IMO headers should almost invariably be self-contained, instead of
putting the burden on their users to include other headers to make it
work. It's a PITA in a project the size of the kernel, or even just the
drm subsystem, to track these cases when you modify includes in either
users or the headers being included.

The exception to this are headers that are not to be included directly
by users, but rather by other headers as an implementation detail. There
may be such cases in include/linux, but not under include/drm.


BR,
Jani.


(*) Fine, there's one *intentional* special case in i915.

-- 
Jani Nikula, Intel