[Intel-gfx] [PATCH v4 5/5] i915: add documentation to intel_engine_cs

[Jani Nikula]

On Wed, 04 Apr 2018, Joonas Lahtinen <joonas.lahtinen at linux.intel.com> wrote:
> + Jani for Sphinx
>
> Quoting Rogovin, Kevin (2018-04-03 17:34:49)
>> I am somewhat tempted to just drop this patch or add more documentation. The function pointers are used in the code common
>> to the legacy way and LRC way of submitting batchbuffers to the GPU, so they should have somekind of contract to what they are
>> supposed to do... but spelling out that contract might be a bit much...
>> 
>> Opinions?
>
> No big feelings to either direction, you could add a documentation block
> for the flow nearby.
>
> If the struct members are referred to from documentation blocks, how far
> are we from generating warnings if a patch renames something that
> becomes non-existent in .rst or documentation block? (this one for Jani)

So first of all, the comments here are not kernel-doc comments, just
regular comments. It's just free text.

If you want them to be kernel-doc comments, included to some fancy
generated documentation, you'll have to follow the guide at [1], wrap
them in /** and */ and add the @member: tag at the start.

Specifically, struct::member is not a thing. If you want to reference
documented struct members in kernel-doc comments, you'll need to use
&struct_name->member or &struct_name.member.

BR,
Jani.


-- 
Jani Nikula, Intel Open Source Technology Center