On Thu, Dec 1, 2016 at 12:12 PM, Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> wrote:
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.
On Wed, 30 Nov 2016, Daniel Vetter <daniel@xxxxxxxx> wrote:
> On Tue, Nov 29, 2016 at 05:00:55PM +0000, Robert Bragg wrote:
>> +.. kernel-doc:: drivers/gpu/drm/i915/i915_perf.c One real issue with listing everything separately is that kernel-doc
>> + :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.
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."
"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@xxxxxxxxxxxxxxxxxxxxx https://lists.freedesktop.org/mailman/listinfo/intel-gfx
