[Intel-gfx] [PATCH] drm/i915/perf: More documentation hooked to i915.rst

[Robert Bragg]

On Thu, Dec 1, 2016 at 12:12 PM, Jani Nikula <jani.nikula at linux.intel.com>
wrote:

> On Wed, 30 Nov 2016, Daniel Vetter <daniel at ffwll.ch> wrote:
> > On Tue, Nov 29, 2016 at 05:00:55PM +0000, Robert Bragg wrote:
> >> +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> >> +   :functions: i915_perf_init
> >> +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> >> +   :functions: i915_perf_fini
> >> +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> >> +   :functions: i915_perf_register
> >> +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> >> +   :functions: i915_perf_unregister
> >> +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> >> +   :functions: i915_perf_open_ioctl
> >> +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c
> >> +   :functions: i915_perf_release
> >
> > One potential issue with listing everything explicitly is that if someone
> > ever (and this is bound to happen) adds a new function, they'll forget to
> > add it. Hence we just pull them all in, and if you want to refernce some
> > specifically, do that in the overview sections.
>
> One real issue with listing everything separately is that kernel-doc
> parses the source file once per every kernel-doc directive.
>

Yeah, this is unfortunate and I'd originally hoped I could pass an ordered
list which could reduce how often kernel-doc is run. In practice I haven't
seen a performance problem with doing this though.


>
> Also, doesn't Sphinx complain about not having a blank line to end the
> indented block after the directive? It might not, but I thought it
> might.
>

Apparently it's ok, I've been generating and previewing the documentation
and haven't seen a warning about this.

>From the restructure text spec, regarding white space:
"Blank lines may be omitted when the markup makes element separation
unambiguous, in conjunction with indentation."

Regards,
- Robert


>
> BR,
> Jani.
>
>
> --
> Jani Nikula, Intel Open Source Technology Center
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.freedesktop.org/archives/intel-gfx/attachments/20161202/1ce40921/attachment.html>