[01/20] drm/doc: Fix more kerneldoc/sphinx warnings
diff mbox

Message ID 1470750091-16627-2-git-send-email-daniel.vetter@ffwll.ch
State New
Headers show

Commit Message

Daniel Vetter Aug. 9, 2016, 1:41 p.m. UTC
These are the leftovers I could only track down using keep_warnings =
True. For some of them we might want to update our style guide on how
to reference structures and constants, not sure ...

Cc: Markus Heiser <markus.heiser@darmarit.de>
Cc: Jonathan Corbet <corbet@lwn.net>
Cc: linux-doc@vger.kernel.org
Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
---
 drivers/gpu/drm/drm_crtc.c              |  4 ++--
 drivers/gpu/drm/drm_fb_helper.c         |  2 +-
 drivers/gpu/drm/drm_irq.c               |  8 +++----
 drivers/gpu/drm/drm_simple_kms_helper.c |  2 +-
 drivers/gpu/drm/i915/i915_vgpu.c        | 42 ++++++++++++++++-----------------
 drivers/gpu/drm/i915/intel_audio.c      |  6 ++---
 drivers/gpu/drm/i915/intel_guc_fwif.h   |  5 ++--
 include/drm/drm_crtc.h                  |  8 +++----
 include/drm/drm_gem.h                   |  4 ++--
 9 files changed, 41 insertions(+), 40 deletions(-)

Comments

Jani Nikula Aug. 11, 2016, 8:15 a.m. UTC | #1
On Tue, 09 Aug 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> These are the leftovers I could only track down using keep_warnings =
> True. For some of them we might want to update our style guide on how
> to reference structures and constants, not sure ...
>
> Cc: Markus Heiser <markus.heiser@darmarit.de>
> Cc: Jonathan Corbet <corbet@lwn.net>
> Cc: linux-doc@vger.kernel.org
> Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> ---
>  drivers/gpu/drm/drm_crtc.c              |  4 ++--
>  drivers/gpu/drm/drm_fb_helper.c         |  2 +-
>  drivers/gpu/drm/drm_irq.c               |  8 +++----
>  drivers/gpu/drm/drm_simple_kms_helper.c |  2 +-
>  drivers/gpu/drm/i915/i915_vgpu.c        | 42 ++++++++++++++++-----------------
>  drivers/gpu/drm/i915/intel_audio.c      |  6 ++---
>  drivers/gpu/drm/i915/intel_guc_fwif.h   |  5 ++--
>  include/drm/drm_crtc.h                  |  8 +++----
>  include/drm/drm_gem.h                   |  4 ++--
>  9 files changed, 41 insertions(+), 40 deletions(-)
>
> diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
> index 3d03eb1e3b63..ad38a8a31898 100644
> --- a/drivers/gpu/drm/drm_crtc.c
> +++ b/drivers/gpu/drm/drm_crtc.c
> @@ -1272,7 +1272,7 @@ static unsigned int drm_num_planes(struct drm_device *dev)
>   * @plane: plane object to init
>   * @possible_crtcs: bitmask of possible CRTCs
>   * @funcs: callbacks for the new plane
> - * @formats: array of supported formats (%DRM_FORMAT_*)
> + * @formats: array of supported formats (DRM_FORMAT\_\*)

Future idea: If we turned DRM_FORMAT_* into an enum instead of a
plethora of macros, we could reference the enum here. Not to mention the
code being self-documenting too.

>   * @format_count: number of elements in @formats
>   * @type: type of plane (overlay, primary, cursor)
>   * @name: printf style format string for the plane name, or NULL for default name
> @@ -1387,7 +1387,7 @@ static void drm_plane_unregister_all(struct drm_device *dev)
>   * @plane: plane object to init
>   * @possible_crtcs: bitmask of possible CRTCs
>   * @funcs: callbacks for the new plane
> - * @formats: array of supported formats (%DRM_FORMAT_*)
> + * @formats: array of supported formats (DRM_FORMAT\_\*)
>   * @format_count: number of elements in @formats
>   * @is_primary: plane type (primary vs overlay)
>   *
> diff --git a/drivers/gpu/drm/drm_fb_helper.c b/drivers/gpu/drm/drm_fb_helper.c
> index ce54e985d91b..95f405e04f5f 100644
> --- a/drivers/gpu/drm/drm_fb_helper.c
> +++ b/drivers/gpu/drm/drm_fb_helper.c
> @@ -2194,7 +2194,7 @@ EXPORT_SYMBOL(drm_fb_helper_initial_config);
>   * @fb_helper: the drm_fb_helper
>   *
>   * Scan the connectors attached to the fb_helper and try to put together a
> - * setup after *notification of a change in output configuration.
> + * setup after notification of a change in output configuration.
>   *
>   * Called at runtime, takes the mode config locks to be able to check/change the
>   * modeset configuration. Must be run from process context (which usually means
> diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c
> index 9bdce1cb6c5c..10611a936059 100644
> --- a/drivers/gpu/drm/drm_irq.c
> +++ b/drivers/gpu/drm/drm_irq.c
> @@ -713,10 +713,10 @@ EXPORT_SYMBOL(drm_calc_timestamping_constants);
>   * Negative value on error, failure or if not supported in current
>   * video mode:
>   *
> - * -EINVAL   - Invalid CRTC.
> - * -EAGAIN   - Temporary unavailable, e.g., called before initial modeset.
> - * -ENOTSUPP - Function not supported in current display mode.
> - * -EIO      - Failed, e.g., due to failed scanout position query.
> + * -EINVAL    Invalid CRTC.
> + * -EAGAIN    Temporary unavailable, e.g., called before initial modeset.
> + * -ENOTSUPP  Function not supported in current display mode.
> + * -EIO       Failed, e.g., due to failed scanout position query.
>   *
>   * Returns or'ed positive status flags on success:
>   *
> diff --git a/drivers/gpu/drm/drm_simple_kms_helper.c b/drivers/gpu/drm/drm_simple_kms_helper.c
> index 0db36d27e90b..4e1de31f072b 100644
> --- a/drivers/gpu/drm/drm_simple_kms_helper.c
> +++ b/drivers/gpu/drm/drm_simple_kms_helper.c
> @@ -152,7 +152,7 @@ static const struct drm_plane_funcs drm_simple_kms_plane_funcs = {
>   * @dev: DRM device
>   * @pipe: simple display pipe object to initialize
>   * @funcs: callbacks for the display pipe (optional)
> - * @formats: array of supported formats (%DRM_FORMAT_*)
> + * @formats: array of supported formats (DRM_FORMAT\_\*)
>   * @format_count: number of elements in @formats
>   * @connector: connector to attach and register
>   *
> diff --git a/drivers/gpu/drm/i915/i915_vgpu.c b/drivers/gpu/drm/i915/i915_vgpu.c
> index 142bac976919..ca2e91259948 100644
> --- a/drivers/gpu/drm/i915/i915_vgpu.c
> +++ b/drivers/gpu/drm/i915/i915_vgpu.c
> @@ -156,27 +156,27 @@ static int vgt_balloon_space(struct drm_mm *mm,
>   * host point of view, the graphic address space is partitioned by multiple
>   * vGPUs in different VMs. ::
>   *
> - *                        vGPU1 view         Host view
> - *             0 ------> +-----------+     +-----------+
> - *               ^       |###########|     |   vGPU3   |
> - *               |       |###########|     +-----------+
> - *               |       |###########|     |   vGPU2   |
> - *               |       +-----------+     +-----------+
> - *        mappable GM    | available | ==> |   vGPU1   |
> - *               |       +-----------+     +-----------+
> - *               |       |###########|     |           |
> - *               v       |###########|     |   Host    |
> - *               +=======+===========+     +===========+
> - *               ^       |###########|     |   vGPU3   |
> - *               |       |###########|     +-----------+
> - *               |       |###########|     |   vGPU2   |
> - *               |       +-----------+     +-----------+
> - *      unmappable GM    | available | ==> |   vGPU1   |
> - *               |       +-----------+     +-----------+
> - *               |       |###########|     |           |
> - *               |       |###########|     |   Host    |
> - *               v       |###########|     |           |
> - * total GM size ------> +-----------+     +-----------+
> + *                         vGPU1 view         Host view
> + *              0 ------> +-----------+     +-----------+
> + *                ^       |###########|     |   vGPU3   |
> + *                |       |###########|     +-----------+
> + *                |       |###########|     |   vGPU2   |
> + *                |       +-----------+     +-----------+
> + *         mappable GM    | available | ==> |   vGPU1   |
> + *                |       +-----------+     +-----------+
> + *                |       |###########|     |           |
> + *                v       |###########|     |   Host    |
> + *                +=======+===========+     +===========+
> + *                ^       |###########|     |   vGPU3   |
> + *                |       |###########|     +-----------+
> + *                |       |###########|     |   vGPU2   |
> + *                |       +-----------+     +-----------+
> + *       unmappable GM    | available | ==> |   vGPU1   |
> + *                |       +-----------+     +-----------+
> + *                |       |###########|     |           |
> + *                |       |###########|     |   Host    |
> + *                v       |###########|     |           |
> + *  total GM size ------> +-----------+     +-----------+
>   *
>   * Returns:
>   * zero on success, non-zero if configuration invalid or ballooning failed
> 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.

An alternative would be to change kernel-doc to work for the latter too.

>   * defined in graphics driver and called in audio driver. The
> - * struct i915_audio_component_audio_ops *audio_ops is called from i915 driver.
> + * struct &i915_audio_component_audio_ops @audio_ops is called from i915 driver.
>   */
>  
>  static const struct {
> diff --git a/drivers/gpu/drm/i915/intel_guc_fwif.h b/drivers/gpu/drm/i915/intel_guc_fwif.h
> index 944786d7075b..e40db2d2ae99 100644
> --- a/drivers/gpu/drm/i915/intel_guc_fwif.h
> +++ b/drivers/gpu/drm/i915/intel_guc_fwif.h
> @@ -155,6 +155,7 @@
>   *
>   *     +-------------------------------+
>   *     |        guc_css_header         |
> + *     |                               |
>   *     | contains major/minor version  |
>   *     +-------------------------------+
>   *     |             uCode             |
> @@ -176,10 +177,10 @@
>   *
>   * 1. Header, uCode and RSA are must-have components.
>   * 2. All firmware components, if they present, are in the sequence illustrated
> - * in the layout table above.
> + *    in the layout table above.
>   * 3. Length info of each component can be found in header, in dwords.
>   * 4. Modulus and exponent key are not required by driver. They may not appear
> - * in fw. So driver will load a truncated firmware in this case.
> + *    in fw. So driver will load a truncated firmware in this case.
>   */
>  
>  struct guc_css_header {
> diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
> index 44e070800b6d..a47b48c7b93e 100644
> --- a/include/drm/drm_crtc.h
> +++ b/include/drm/drm_crtc.h
> @@ -1195,7 +1195,7 @@ struct drm_encoder_funcs {
>   * @head: list management
>   * @base: base KMS object
>   * @name: human readable name, can be overwritten by the driver
> - * @encoder_type: one of the %DRM_MODE_ENCODER_<foo> types in drm_mode.h
> + * @encoder_type: one of the DRM_MODE_ENCODER_<foo> types in drm_mode.h
>   * @possible_crtcs: bitmask of potential CRTC bindings
>   * @possible_clones: bitmask of potential sibling encoders for cloning
>   * @crtc: currently bound CRTC
> @@ -1248,7 +1248,7 @@ struct drm_encoder {
>   * @head: list management
>   * @base: base KMS object
>   * @name: human readable name, can be overwritten by the driver
> - * @connector_type: one of the %DRM_MODE_CONNECTOR_<foo> types from drm_mode.h
> + * @connector_type: one of the DRM_MODE_CONNECTOR_<foo> types from drm_mode.h

Ditto here about making DRM_MODE_* an enum.

>   * @connector_type_id: index into connector type enum
>   * @interlace_allowed: can this connector handle interlaced modes?
>   * @doublescan_allowed: can this connector handle doublescan?
> @@ -1261,11 +1261,11 @@ struct drm_encoder {
>   * @funcs: connector control functions
>   * @edid_blob_ptr: DRM property containing EDID if present
>   * @properties: property tracking for this connector
> - * @polled: a %DRM_CONNECTOR_POLL_<foo> value for core driven polling
> + * @polled: a DRM_CONNECTOR_POLL_<foo> value for core driven polling
>   * @dpms: current dpms state
>   * @helper_private: mid-layer private data
>   * @cmdline_mode: mode line parsed from the kernel cmdline for this connector
> - * @force: a %DRM_FORCE_<foo> state for forced mode sets
> + * @force: a DRM_FORCE_<foo> state for forced mode sets
>   * @override_edid: has the EDID been overwritten through debugfs for testing?
>   * @encoder_ids: valid encoders for this connector
>   * @encoder: encoder driving this connector, if any
> diff --git a/include/drm/drm_gem.h b/include/drm/drm_gem.h
> index fca1cd1b9c26..9f63736e6163 100644
> --- a/include/drm/drm_gem.h
> +++ b/include/drm/drm_gem.h
> @@ -210,8 +210,8 @@ drm_gem_object_reference(struct drm_gem_object *obj)
>   * drm_gem_object_unreference_unlocked().
>   *
>   * Drivers should never call this directly in their code. Instead they should
> - * wrap it up into a driver_gem_object_unreference(struct driver_gem_object
> - * *obj) wrapper function, and use that. Shared code should never call this, to
> + * wrap it up into a ``driver_gem_object_unreference(struct driver_gem_object
> + * *obj)`` wrapper function, and use that. Shared code should never call this, to
>   * avoid breaking drivers by accident which still depend upon dev->struct_mutex
>   * locking.
>   */
Ville Syrjälä Aug. 11, 2016, 8:23 a.m. UTC | #2
On Thu, Aug 11, 2016 at 11:15:13AM +0300, Jani Nikula wrote:
> On Tue, 09 Aug 2016, Daniel Vetter <daniel.vetter@ffwll.ch> wrote:
> > These are the leftovers I could only track down using keep_warnings =
> > True. For some of them we might want to update our style guide on how
> > to reference structures and constants, not sure ...
> >
> > Cc: Markus Heiser <markus.heiser@darmarit.de>
> > Cc: Jonathan Corbet <corbet@lwn.net>
> > Cc: linux-doc@vger.kernel.org
> > Signed-off-by: Daniel Vetter <daniel.vetter@intel.com>
> > ---
> >  drivers/gpu/drm/drm_crtc.c              |  4 ++--
> >  drivers/gpu/drm/drm_fb_helper.c         |  2 +-
> >  drivers/gpu/drm/drm_irq.c               |  8 +++----
> >  drivers/gpu/drm/drm_simple_kms_helper.c |  2 +-
> >  drivers/gpu/drm/i915/i915_vgpu.c        | 42 ++++++++++++++++-----------------
> >  drivers/gpu/drm/i915/intel_audio.c      |  6 ++---
> >  drivers/gpu/drm/i915/intel_guc_fwif.h   |  5 ++--
> >  include/drm/drm_crtc.h                  |  8 +++----
> >  include/drm/drm_gem.h                   |  4 ++--
> >  9 files changed, 41 insertions(+), 40 deletions(-)
> >
> > diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
> > index 3d03eb1e3b63..ad38a8a31898 100644
> > --- a/drivers/gpu/drm/drm_crtc.c
> > +++ b/drivers/gpu/drm/drm_crtc.c
> > @@ -1272,7 +1272,7 @@ static unsigned int drm_num_planes(struct drm_device *dev)
> >   * @plane: plane object to init
> >   * @possible_crtcs: bitmask of possible CRTCs
> >   * @funcs: callbacks for the new plane
> > - * @formats: array of supported formats (%DRM_FORMAT_*)
> > + * @formats: array of supported formats (DRM_FORMAT\_\*)
> 
> Future idea: If we turned DRM_FORMAT_* into an enum instead of a
> plethora of macros, we could reference the enum here. Not to mention the
> code being self-documenting too.

DRM_FORMAT_* is uapi, so can't change it.
Jani Nikula Aug. 11, 2016, 8:23 a.m. UTC | #3
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.

BR,
Jani.
Markus Heiser Aug. 11, 2016, 9:29 a.m. UTC | #4
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

Patch
diff mbox

diff --git a/drivers/gpu/drm/drm_crtc.c b/drivers/gpu/drm/drm_crtc.c
index 3d03eb1e3b63..ad38a8a31898 100644
--- a/drivers/gpu/drm/drm_crtc.c
+++ b/drivers/gpu/drm/drm_crtc.c
@@ -1272,7 +1272,7 @@  static unsigned int drm_num_planes(struct drm_device *dev)
  * @plane: plane object to init
  * @possible_crtcs: bitmask of possible CRTCs
  * @funcs: callbacks for the new plane
- * @formats: array of supported formats (%DRM_FORMAT_*)
+ * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
  * @type: type of plane (overlay, primary, cursor)
  * @name: printf style format string for the plane name, or NULL for default name
@@ -1387,7 +1387,7 @@  static void drm_plane_unregister_all(struct drm_device *dev)
  * @plane: plane object to init
  * @possible_crtcs: bitmask of possible CRTCs
  * @funcs: callbacks for the new plane
- * @formats: array of supported formats (%DRM_FORMAT_*)
+ * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
  * @is_primary: plane type (primary vs overlay)
  *
diff --git a/drivers/gpu/drm/drm_fb_helper.c b/drivers/gpu/drm/drm_fb_helper.c
index ce54e985d91b..95f405e04f5f 100644
--- a/drivers/gpu/drm/drm_fb_helper.c
+++ b/drivers/gpu/drm/drm_fb_helper.c
@@ -2194,7 +2194,7 @@  EXPORT_SYMBOL(drm_fb_helper_initial_config);
  * @fb_helper: the drm_fb_helper
  *
  * Scan the connectors attached to the fb_helper and try to put together a
- * setup after *notification of a change in output configuration.
+ * setup after notification of a change in output configuration.
  *
  * Called at runtime, takes the mode config locks to be able to check/change the
  * modeset configuration. Must be run from process context (which usually means
diff --git a/drivers/gpu/drm/drm_irq.c b/drivers/gpu/drm/drm_irq.c
index 9bdce1cb6c5c..10611a936059 100644
--- a/drivers/gpu/drm/drm_irq.c
+++ b/drivers/gpu/drm/drm_irq.c
@@ -713,10 +713,10 @@  EXPORT_SYMBOL(drm_calc_timestamping_constants);
  * Negative value on error, failure or if not supported in current
  * video mode:
  *
- * -EINVAL   - Invalid CRTC.
- * -EAGAIN   - Temporary unavailable, e.g., called before initial modeset.
- * -ENOTSUPP - Function not supported in current display mode.
- * -EIO      - Failed, e.g., due to failed scanout position query.
+ * -EINVAL    Invalid CRTC.
+ * -EAGAIN    Temporary unavailable, e.g., called before initial modeset.
+ * -ENOTSUPP  Function not supported in current display mode.
+ * -EIO       Failed, e.g., due to failed scanout position query.
  *
  * Returns or'ed positive status flags on success:
  *
diff --git a/drivers/gpu/drm/drm_simple_kms_helper.c b/drivers/gpu/drm/drm_simple_kms_helper.c
index 0db36d27e90b..4e1de31f072b 100644
--- a/drivers/gpu/drm/drm_simple_kms_helper.c
+++ b/drivers/gpu/drm/drm_simple_kms_helper.c
@@ -152,7 +152,7 @@  static const struct drm_plane_funcs drm_simple_kms_plane_funcs = {
  * @dev: DRM device
  * @pipe: simple display pipe object to initialize
  * @funcs: callbacks for the display pipe (optional)
- * @formats: array of supported formats (%DRM_FORMAT_*)
+ * @formats: array of supported formats (DRM_FORMAT\_\*)
  * @format_count: number of elements in @formats
  * @connector: connector to attach and register
  *
diff --git a/drivers/gpu/drm/i915/i915_vgpu.c b/drivers/gpu/drm/i915/i915_vgpu.c
index 142bac976919..ca2e91259948 100644
--- a/drivers/gpu/drm/i915/i915_vgpu.c
+++ b/drivers/gpu/drm/i915/i915_vgpu.c
@@ -156,27 +156,27 @@  static int vgt_balloon_space(struct drm_mm *mm,
  * host point of view, the graphic address space is partitioned by multiple
  * vGPUs in different VMs. ::
  *
- *                        vGPU1 view         Host view
- *             0 ------> +-----------+     +-----------+
- *               ^       |###########|     |   vGPU3   |
- *               |       |###########|     +-----------+
- *               |       |###########|     |   vGPU2   |
- *               |       +-----------+     +-----------+
- *        mappable GM    | available | ==> |   vGPU1   |
- *               |       +-----------+     +-----------+
- *               |       |###########|     |           |
- *               v       |###########|     |   Host    |
- *               +=======+===========+     +===========+
- *               ^       |###########|     |   vGPU3   |
- *               |       |###########|     +-----------+
- *               |       |###########|     |   vGPU2   |
- *               |       +-----------+     +-----------+
- *      unmappable GM    | available | ==> |   vGPU1   |
- *               |       +-----------+     +-----------+
- *               |       |###########|     |           |
- *               |       |###########|     |   Host    |
- *               v       |###########|     |           |
- * total GM size ------> +-----------+     +-----------+
+ *                         vGPU1 view         Host view
+ *              0 ------> +-----------+     +-----------+
+ *                ^       |###########|     |   vGPU3   |
+ *                |       |###########|     +-----------+
+ *                |       |###########|     |   vGPU2   |
+ *                |       +-----------+     +-----------+
+ *         mappable GM    | available | ==> |   vGPU1   |
+ *                |       +-----------+     +-----------+
+ *                |       |###########|     |           |
+ *                v       |###########|     |   Host    |
+ *                +=======+===========+     +===========+
+ *                ^       |###########|     |   vGPU3   |
+ *                |       |###########|     +-----------+
+ *                |       |###########|     |   vGPU2   |
+ *                |       +-----------+     +-----------+
+ *       unmappable GM    | available | ==> |   vGPU1   |
+ *                |       +-----------+     +-----------+
+ *                |       |###########|     |           |
+ *                |       |###########|     |   Host    |
+ *                v       |###########|     |           |
+ *  total GM size ------> +-----------+     +-----------+
  *
  * Returns:
  * zero on success, non-zero if configuration invalid or ballooning failed
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
  * defined in graphics driver and called in audio driver. The
- * struct i915_audio_component_audio_ops *audio_ops is called from i915 driver.
+ * struct &i915_audio_component_audio_ops @audio_ops is called from i915 driver.
  */
 
 static const struct {
diff --git a/drivers/gpu/drm/i915/intel_guc_fwif.h b/drivers/gpu/drm/i915/intel_guc_fwif.h
index 944786d7075b..e40db2d2ae99 100644
--- a/drivers/gpu/drm/i915/intel_guc_fwif.h
+++ b/drivers/gpu/drm/i915/intel_guc_fwif.h
@@ -155,6 +155,7 @@ 
  *
  *     +-------------------------------+
  *     |        guc_css_header         |
+ *     |                               |
  *     | contains major/minor version  |
  *     +-------------------------------+
  *     |             uCode             |
@@ -176,10 +177,10 @@ 
  *
  * 1. Header, uCode and RSA are must-have components.
  * 2. All firmware components, if they present, are in the sequence illustrated
- * in the layout table above.
+ *    in the layout table above.
  * 3. Length info of each component can be found in header, in dwords.
  * 4. Modulus and exponent key are not required by driver. They may not appear
- * in fw. So driver will load a truncated firmware in this case.
+ *    in fw. So driver will load a truncated firmware in this case.
  */
 
 struct guc_css_header {
diff --git a/include/drm/drm_crtc.h b/include/drm/drm_crtc.h
index 44e070800b6d..a47b48c7b93e 100644
--- a/include/drm/drm_crtc.h
+++ b/include/drm/drm_crtc.h
@@ -1195,7 +1195,7 @@  struct drm_encoder_funcs {
  * @head: list management
  * @base: base KMS object
  * @name: human readable name, can be overwritten by the driver
- * @encoder_type: one of the %DRM_MODE_ENCODER_<foo> types in drm_mode.h
+ * @encoder_type: one of the DRM_MODE_ENCODER_<foo> types in drm_mode.h
  * @possible_crtcs: bitmask of potential CRTC bindings
  * @possible_clones: bitmask of potential sibling encoders for cloning
  * @crtc: currently bound CRTC
@@ -1248,7 +1248,7 @@  struct drm_encoder {
  * @head: list management
  * @base: base KMS object
  * @name: human readable name, can be overwritten by the driver
- * @connector_type: one of the %DRM_MODE_CONNECTOR_<foo> types from drm_mode.h
+ * @connector_type: one of the DRM_MODE_CONNECTOR_<foo> types from drm_mode.h
  * @connector_type_id: index into connector type enum
  * @interlace_allowed: can this connector handle interlaced modes?
  * @doublescan_allowed: can this connector handle doublescan?
@@ -1261,11 +1261,11 @@  struct drm_encoder {
  * @funcs: connector control functions
  * @edid_blob_ptr: DRM property containing EDID if present
  * @properties: property tracking for this connector
- * @polled: a %DRM_CONNECTOR_POLL_<foo> value for core driven polling
+ * @polled: a DRM_CONNECTOR_POLL_<foo> value for core driven polling
  * @dpms: current dpms state
  * @helper_private: mid-layer private data
  * @cmdline_mode: mode line parsed from the kernel cmdline for this connector
- * @force: a %DRM_FORCE_<foo> state for forced mode sets
+ * @force: a DRM_FORCE_<foo> state for forced mode sets
  * @override_edid: has the EDID been overwritten through debugfs for testing?
  * @encoder_ids: valid encoders for this connector
  * @encoder: encoder driving this connector, if any
diff --git a/include/drm/drm_gem.h b/include/drm/drm_gem.h
index fca1cd1b9c26..9f63736e6163 100644
--- a/include/drm/drm_gem.h
+++ b/include/drm/drm_gem.h
@@ -210,8 +210,8 @@  drm_gem_object_reference(struct drm_gem_object *obj)
  * drm_gem_object_unreference_unlocked().
  *
  * Drivers should never call this directly in their code. Instead they should
- * wrap it up into a driver_gem_object_unreference(struct driver_gem_object
- * *obj) wrapper function, and use that. Shared code should never call this, to
+ * wrap it up into a ``driver_gem_object_unreference(struct driver_gem_object
+ * *obj)`` wrapper function, and use that. Shared code should never call this, to
  * avoid breaking drivers by accident which still depend upon dev->struct_mutex
  * locking.
  */