[Intel-gfx] [PATCH 01/20] drm/doc: Fix more kerneldoc/sphinx warnings

[Markus Heiser]

Am 11.08.2016 um 10:23 schrieb Jani Nikula <jani.nikula at linux.intel.com>:

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