[PATCH v3 00/37] drm/i915: fix kernel-doc issues
From: Mauro Carvalho Chehab
Date: Fri Sep 09 2022 - 03:36:45 EST
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