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

[Joonas Lahtinen]

Quoting Jani Nikula (2018-04-04 12:48:55)
> 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.

That was known, but thanks for reminding. What I was weighing was what's the
likelihood of noticing if some struct members get renamed in a patch and
the documentation breaks.

To be perfectly clear: Are we working towards a clean make htmldocs and
CI nagging when it gets broken?

Regards, Joonas

> 
> BR,
> Jani.
> 
> 
> -- 
> Jani Nikula, Intel Open Source Technology Center