Am 11.08.2016 um 10:23 schrieb Jani Nikula jani.nikula@linux.intel.com:
On Thu, 11 Aug 2016, Jani Nikula jani.nikula@linux.intel.com wrote:
On Tue, 09 Aug 2016, Daniel Vetter daniel.vetter@ffwll.ch 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@vger.kernel.org More majordomo info at http://vger.kernel.org/majordomo-info.html