Am 11.08.2016 um 10:23 schrieb Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx>: > On Thu, 11 Aug 2016, Jani Nikula <jani.nikula@xxxxxxxxxxxxxxx> wrote: >> On Tue, 09 Aug 2016, Daniel Vetter <daniel.vetter@xxxxxxxx> wrote: >>> diff --git a/drivers/gpu/drm/i915/intel_audio.c b/drivers/gpu/drm/i915/intel_audio.c >>> index d32f586f9c05..85389cdd0bec 100644 >>> --- a/drivers/gpu/drm/i915/intel_audio.c >>> +++ b/drivers/gpu/drm/i915/intel_audio.c >>> @@ -51,10 +51,10 @@ >>> * related registers. (The notable exception is the power management, not >>> * covered here.) >>> * >>> - * The struct i915_audio_component is used to interact between the graphics >>> - * and audio drivers. The struct i915_audio_component_ops *ops in it is >>> + * The struct &i915_audio_component is used to interact between the graphics >>> + * and audio drivers. The struct &i915_audio_component_ops @ops in it is >> >> Please prefer "&struct foo" over "struct &foo". The former makes the >> struct be part of the link text. > > Mmmh, the kernel-doc highlighting code should probably learn about "&struct > foo" spread to two lines. my 2cent thoughts: the kernel-doc syntax is weak and ambiguous. This remains mainly in tagging only with a start-tag or only with a end-tag e.g: * sectioning: "Return:" --> end-tag just ":" * fields: "@arg1:" --> better * highlight/ref: start tag [@%$&] / no end tag the most ambiguous is highlighting, known quirks [1]. I tried to improve it in the kernel-doc parser, but haven't found any good or better reg-expressions yet. We had this already and I won't restart the discussion, just to remember: In my POC I tried to handle this quirks by distinguish *vintage* from *modern* markup and in my first attempt I dropped the kernel-doc highlight markups from the *modern* syntax. My conclusion is, conceptional we should not try to extend the wacky kernel-doc syntax supporting e.g. multi-line markup constructs, particularly if there is a reST markup available. We should only improve the kernel-doc reg-expressions e.g. not to have *fails-match* for highlighting on common things like a e-mail addresses. [1] http://www.spinics.net/lists/linux-media/msg103145.html -- Markus -- > > BR, > Jani. > > -- > Jani Nikula, Intel Open Source Technology Center > -- > To unsubscribe from this list: send the line "unsubscribe linux-doc" in > the body of a message to majordomo@xxxxxxxxxxxxxxx > More majordomo info at http://vger.kernel.org/majordomo-info.html -- To unsubscribe from this list: send the line "unsubscribe linux-doc" in the body of a message to majordomo@xxxxxxxxxxxxxxx More majordomo info at http://vger.kernel.org/majordomo-info.html
