On Thu, Dec 1, 2016 at 12:12 PM, Jani Nikula <jani.nik...@linux.intel.com> wrote:
> On Wed, 30 Nov 2016, Daniel Vetter <dan...@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 >
_______________________________________________ Intel-gfx mailing list Intel-gfx@lists.freedesktop.org https://lists.freedesktop.org/mailman/listinfo/intel-gfx