drm/i915: fix kernel-doc issues

There are several kernel-doc markups along the i915 driver that aren't part of the i915.rst file, nor are included on any other file under Documentation. Maybe due to that, there are several kernel-doc markups that report problems when checked with scripts/kernel-doc. More than that, some of them also have problems when actually integrated at the building system, as reported by Sphinx.

Along the issues we have:

- renamed symbols where the prototype doesn't match the kernel-doc name;
- some markups doesn't have the symbol name on it;
- typos when defining parameter;
- some parameters are missing;
- some ascii artwork aren't properly displayed after parsed by Sphinx;
- some other tags produce bad results and warnings after parsed by html build;
- some "/**" patterns exist on places that aren't kernel-doc markups.

This series, against drm-tip, fix all the above issues and all all such files to i915.rst. This way, it will be easier to avoid other problems to be introduced.

While here, I also added SPDX on two display files. Besides being the current way to indicate the license, it also makes easier to find all files with kernel-doc markups, as all it is needed is to search for "/**" at i915 files to know what of them have embedded documentation.

PS.: my end goal here is to ensure that the TLB patch series I'm about to send will be properly documented. For that to happen, let's first fix all warnings when building the documentation ;-)

---

v3:
- Dropped patches with issues already fixed;
- Addressed Rodrigo's comments.

v2:
- Added 3 already-existing patches form other PRs addressing some of the issues. The subjects were renamed, in order to describe what they're doing.
- Fixed checkpatch warnings;
- Added 4 additional patches at the end, documenting some structs at i915_gem_object_types.h and intel_gt_pm.h, plus adding intel-guc.c internal functions to the generated documentation.

Mauro Carvalho Chehab (37):
drm/i915: fix kernel-doc trivial warnings on i915/*.[ch] files drm/i915: display: fix kernel-doc markup warnings drm/i915: gt: fix some Kernel-doc issues
drm/i915: gvt: fix kernel-doc trivial warnings
drm/i915: gem: fix some Kernel-doc issues
drm/i915: intel_wakeref.h: fix some kernel-doc markups drm/i915: i915_gem_ttm: fix a kernel-doc markup
drm/i915: i915_gem_ttm_pm.c: fix kernel-doc markups drm/i915: gem: add kernel-doc description for some function parameters drm/i915: i915_gpu_error.c: document dump_flags
drm/i915: document kernel-doc trivial issues
drm/i915: intel_dp_link_training.c: fix kernel-doc markup drm/i915: intel_fb: fix a kernel-doc issue with Sphinx drm/i915: skl_scaler: fix return value kernel-doc markup drm/i915: intel_pm.c: fix some ascii artwork at kernel-doc drm/i915: i915_gem_region.h: fix i915_gem_apply_to_region_ops doc drm/i915: i915_gem_wait.c: fix a kernel-doc markup drm/i915: fix i915_gem_ttm_move.c DOC: markup
drm/i915: stop using kernel-doc markups for something else drm/i915: dvo_ch7xxx.c: use SPDX header
drm/i915: dvo_sil164.c: use SPDX header
drm/i915: i915_vma_resource.c: fix some kernel-doc markups drm/i915: i915_gem.c fix a kernel-doc issue
drm/i915: i915_scatterlist.h: fix some kernel-doc markups drm/i915: i915_deps: use a shorter title markup
docs: gpu: i915.rst: display: add kernel-doc markups
docs: gpu: i915.rst: gt: add more kernel-doc markups
docs: gpu: i915.rst: GuC: add more kernel-doc markups
docs: gpu: i915.rst: GVT: add more kernel-doc markups
docs: gpu: i915.rst: PM: add more kernel-doc markups
docs: gpu: i915.rst: GEM/TTM: add more kernel-doc markups
docs: gpu: i915.rst: add the remaining kernel-doc markup files drm/i915 i915_gem_object_types.h: document struct i915_lut_handle drm/i915: document struct drm_i915_gem_object
drm/i915: add descriptions for some RPM macros at intel_gt_pm.h drm/i915: add GuC functions to the documentation
drm/i915: be consistent with kernel-doc function declaration

 Documentation/gpu/i915.rst                    | 283 +++++++++++++++++-
 drivers/gpu/drm/i915/display/dvo_ch7017.c     |  26 +-
 drivers/gpu/drm/i915/display/dvo_ch7xxx.c     |  39 +--
 drivers/gpu/drm/i915/display/dvo_sil164.c     |  32 +-
 drivers/gpu/drm/i915/display/intel_atomic.c   |   2 +-
 drivers/gpu/drm/i915/display/intel_audio.c    |   4 +-
 drivers/gpu/drm/i915/display/intel_crtc.c     |   4 +-
 .../drm/i915/display/intel_display_debugfs.c  |   2 +-
 .../drm/i915/display/intel_display_power.c    |   2 +-
 .../drm/i915/display/intel_display_types.h    |   2 +-
 drivers/gpu/drm/i915/display/intel_dmc.c      |  10 +-
 .../drm/i915/display/intel_dp_link_training.c |   2 +
 drivers/gpu/drm/i915/display/intel_dsb.c      |  10 +-
 drivers/gpu/drm/i915/display/intel_dvo_dev.h  |   6 +-
 drivers/gpu/drm/i915/display/intel_fb.c       |   2 +-
 .../gpu/drm/i915/display/intel_lpe_audio.c    |   8 +-
 drivers/gpu/drm/i915/display/intel_sdvo.c     |   4 +-
 drivers/gpu/drm/i915/display/intel_tc.c       |   2 +-
 drivers/gpu/drm/i915/display/intel_tv.c       |   2 +-
 drivers/gpu/drm/i915/display/skl_scaler.c     |   6 +-
 drivers/gpu/drm/i915/gem/i915_gem_create.c    |   8 +-
 drivers/gpu/drm/i915/gem/i915_gem_domain.c    |  17 +-
 drivers/gpu/drm/i915/gem/i915_gem_object.c    |   2 +
 drivers/gpu/drm/i915/gem/i915_gem_object.h    |   2 +-
 .../gpu/drm/i915/gem/i915_gem_object_types.h  | 212 ++++++++++---
 drivers/gpu/drm/i915/gem/i915_gem_region.h    |   8 +-
 drivers/gpu/drm/i915/gem/i915_gem_ttm.c       |   2 +
 drivers/gpu/drm/i915/gem/i915_gem_ttm.h       |   1 +
 drivers/gpu/drm/i915/gem/i915_gem_ttm_move.c  |   4 +-
 drivers/gpu/drm/i915/gem/i915_gem_ttm_pm.c    |   8 +-
 drivers/gpu/drm/i915/gem/i915_gem_wait.c      |  26 +-
 drivers/gpu/drm/i915/gt/intel_context.h       |   6 +-
 drivers/gpu/drm/i915/gt/intel_context_types.h |  69 +++--
 drivers/gpu/drm/i915/gt/intel_engine_cs.c     |  14 +-
 drivers/gpu/drm/i915/gt/intel_engine_types.h  |   1 +
 drivers/gpu/drm/i915/gt/intel_ggtt_fencing.h  |   2 +-
 drivers/gpu/drm/i915/gt/intel_gt_pm.h         |  51 ++++
 drivers/gpu/drm/i915/gt/intel_gt_types.h      |  12 +-
 drivers/gpu/drm/i915/gt/intel_gtt.h           |   6 +-
 drivers/gpu/drm/i915/gt/intel_reset_types.h   |   4 +-
 drivers/gpu/drm/i915/gt/intel_rps.c           |   4 +-
 .../gpu/drm/i915/gt/intel_timeline_types.h    |   6 +-
 .../drm/i915/gt/shaders/clear_kernel/hsw.asm  |   4 +-
 .../drm/i915/gt/shaders/clear_kernel/ivb.asm  |   4 +-
 drivers/gpu/drm/i915/gt/uc/guc_capture_fwif.h |  24 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc.c        |  10 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc.h        |   2 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_ads.c    |   4 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_fw.c     |   2 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_fwif.h   |   2 +-
 .../gpu/drm/i915/gt/uc/intel_guc_hwconfig.c   |   5 +-
 drivers/gpu/drm/i915/gt/uc/intel_guc_slpc.c   |   8 +-
 drivers/gpu/drm/i915/gt/uc/intel_huc.c        |   4 +-
 drivers/gpu/drm/i915/gt/uc/intel_huc_fw.c     |   2 +-
 drivers/gpu/drm/i915/gt/uc/intel_uc_fw.h      |   2 +-
 drivers/gpu/drm/i915/gvt/cfg_space.c          |   2 +-
 drivers/gpu/drm/i915/gvt/dmabuf.h             |   2 +-
 drivers/gpu/drm/i915/gvt/page_track.c         |   2 +-
 drivers/gpu/drm/i915/gvt/vgpu.c               |   6 +-
 drivers/gpu/drm/i915/i915_active.h            |  14 +-
 drivers/gpu/drm/i915/i915_cmd_parser.c        |   8 +-
 drivers/gpu/drm/i915/i915_deps.c              |   4 +-
 drivers/gpu/drm/i915/i915_drm_client.h        |   2 +-
 drivers/gpu/drm/i915/i915_drv.h               |  24 +-
 drivers/gpu/drm/i915/i915_file_private.h      |   8 +-
 drivers/gpu/drm/i915/i915_gem.c               |  12 +-
 drivers/gpu/drm/i915/i915_gpu_error.c         |   3 +-
 drivers/gpu/drm/i915/i915_gpu_error.h         |   4 +-
 drivers/gpu/drm/i915/i915_pmu.h               |  38 +--
 drivers/gpu/drm/i915/i915_reg_defs.h          |  12 +-
 drivers/gpu/drm/i915/i915_request.h           |   4 +-
 drivers/gpu/drm/i915/i915_scatterlist.c       |   2 +-
 drivers/gpu/drm/i915/i915_scatterlist.h       |  12 +-
 drivers/gpu/drm/i915/i915_utils.h             |   2 +-
 drivers/gpu/drm/i915/i915_vma.c               |   2 +
 drivers/gpu/drm/i915/i915_vma_resource.c      |   4 +-
 drivers/gpu/drm/i915/i915_vma_resource.h      |   3 +-
 drivers/gpu/drm/i915/intel_pm.c               |  33 +-
 drivers/gpu/drm/i915/intel_region_ttm.c       |   3 +-
 drivers/gpu/drm/i915/intel_uncore.h           |   4 +-
 drivers/gpu/drm/i915/intel_wakeref.h          |   4 +-
 drivers/gpu/drm/i915/intel_wopcm.c            |   4 +-
 82 files changed, 826 insertions(+), 378 deletions(-)

2.37.3