[Intel-gfx] [PATCH v2] drm/i915: Add missing docbook chapters for i915 uapi.

[Tvrtko Ursulin]

On 15/07/2021 13:08, Maarten Lankhorst wrote:
> I noticed when grepping for DOC: that those were defined
> in the header, but not actually used. Fix it by removing
> all chapters and the internal annotation, so the docbook
> generated chapters are used.
> 
> Changes since v1:
> - Just remove the chapters, no need for those.
> 
> Signed-off-by: Maarten Lankhorst <maarten.lankhorst at linux.intel.com>
> Link: https://patchwork.freedesktop.org/patch/msgid/20210709113842.651140-1-maarten.lankhorst@linux.intel.com
> ---
>   Documentation/gpu/driver-uapi.rst | 21 ---------------------
>   1 file changed, 21 deletions(-)
> 
> diff --git a/Documentation/gpu/driver-uapi.rst b/Documentation/gpu/driver-uapi.rst
> index 27d0fbe33e87..4411e6919a3d 100644
> --- a/Documentation/gpu/driver-uapi.rst
> +++ b/Documentation/gpu/driver-uapi.rst
> @@ -5,25 +5,4 @@ DRM Driver uAPI
>   drm/i915 uAPI
>   =============
>   
> -Engine Discovery uAPI
> ----------------------
> -
> -.. kernel-doc:: include/uapi/drm/i915_drm.h
> -   :doc: Engine Discovery uAPI
> -
> -Context Engine Map uAPI
> ------------------------
> -
> -.. kernel-doc:: include/uapi/drm/i915_drm.h
> -   :doc: Context Engine Map uAPI
> -
> -Virtual Engine uAPI
> --------------------
> -
> -.. kernel-doc:: include/uapi/drm/i915_drm.h
> -   :doc: Virtual Engine uAPI
> -

Hmm my idea was to have the above three laid out sequentially in the doc 
so the narrative makes sense. Otherwise they are at random locations in 
i915_drm.h so reader cannot get the nice story around high level 
operation and interactions between then. Initially I had this narrative 
right in this file but Daniel wanted it moved into i915_drm.h.

I didn't really understand the commit message to understand what wasn't 
right?

> -i915_drm.h
> -----------
>   .. kernel-doc:: include/uapi/drm/i915_drm.h
> -   :internal:

This one I added to avoid duplicate sections. It won't be a problem if 
they are not referenced from driver-uapi.rst though.

Regards,

Tvrtko