Quoting Jani Nikula (2018-04-04 12:48:55) > On Wed, 04 Apr 2018, Joonas Lahtinen <joonas.lahti...@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 _______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx
