drm/komeda: Fixed warning: Function parameter or member not described

Fixed the warnings: Function parameter or member 'xxx' not described
when make htmldocs

This patch depends on:
- https://patchwork.freedesktop.org/series/54448/
- https://patchwork.freedesktop.org/series/54449/
- https://patchwork.freedesktop.org/series/54450/

v2: Rebase and add reporter

Reported-by: kbuild test robot <lkp@intel.com>
Signed-off-by: James Qian Wang (Arm Technology China) <james.qian.wang@arm.com>
Signed-off-by: Liviu Dudau <liviu.dudau@arm.com>

6 files changed, 85 insertions, 23 deletions

diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_crtc.c b/drivers/gpu/drm/arm/display/komeda/komeda_crtc.c
index 053b1e3e74be..d335fec1b727 100644
--- a/drivers/gpu/drm/arm/display/komeda/komeda_crtc.c
+++ b/drivers/gpu/drm/arm/display/komeda/komeda_crtc.c
@@ -18,9 +18,17 @@
 #include "komeda_dev.h"
 #include "komeda_kms.h"
 
-/* crtc_atomic_check is the final check stage, so beside build a display data
- * pipeline according the crtc_state, but still needs to release/disable the
- * unclaimed pipeline resources.
+/**
+ * komeda_crtc_atomic_check - build display output data flow
+ * @crtc: DRM crtc
+ * @state: the crtc state object
+ *
+ * crtc_atomic_check is the final check stage, so beside build a display data
+ * pipeline according to the crtc_state, but still needs to release or disable
+ * the unclaimed pipeline resources.
+ *
+ * RETURNS:
+ * Zero for success or -errno
  */
 static int
 komeda_crtc_atomic_check(struct drm_crtc *crtc,
diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_dev.h b/drivers/gpu/drm/arm/display/komeda/komeda_dev.h
index 0c3e32b596d9..29e03c4e1ffc 100644
--- a/drivers/gpu/drm/arm/display/komeda/komeda_dev.h
+++ b/drivers/gpu/drm/arm/display/komeda/komeda_dev.h
@@ -120,7 +120,7 @@ struct komeda_dev_funcs {
                       int master_pipe, u32 active_pipes);
 };
 
-/**
+/*
  * DISPLAY_MODE describes how many display been enabled, and which will be
  * passed to CHIP by &komeda_dev_funcs->change_opmode(), then CHIP can do the
  * pipeline resources assignment according to this usage hint.
@@ -145,24 +145,31 @@ enum {
  * control-abilites of device.
  */
 struct komeda_dev {
+        /** @dev: the base device structure */
         struct device *dev;
+        /** @reg_base: the base address of komeda io space */
         u32 __iomem   *reg_base;
 
+        /** @chip: the basic chip information */
         struct komeda_chip_info chip;
         /** @fmt_tbl: initialized by &komeda_dev_funcs->init_format_table */
         struct komeda_format_caps_table fmt_tbl;
         /** @pclk: APB clock for register access */
         struct clk *pclk;
-        /** @mck: HW main engine clk */
+        /** @mclk: HW main engine clk */
         struct clk *mclk;
 
         /** @irq: irq number */
         int irq;
 
-        struct mutex lock; /* used to protect dpmode */
-        u32 dpmode; /* current display mode */
+        /** @lock: used to protect dpmode */
+        struct mutex lock;
+        /** @dpmode: current display mode */
+        u32 dpmode;
 
+        /** @n_pipelines: the number of pipe in @pipelines */
         int n_pipelines;
+        /** @pipelines: the komeda pipelines */
         struct komeda_pipeline *pipelines[KOMEDA_MAX_PIPELINES];
 
         /** @funcs: chip funcs to access to HW */
@@ -175,6 +182,7 @@ struct komeda_dev {
          */
         void *chip_data;
 
+        /** @debugfs_root: root directory of komeda debugfs */
         struct dentry *debugfs_root;
 };
 
diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h b/drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h
index 0de2e4a2afd2..ea2fe190c1e3 100644
--- a/drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h
+++ b/drivers/gpu/drm/arm/display/komeda/komeda_framebuffer.h
@@ -10,11 +10,16 @@
 #include <drm/drm_framebuffer.h>
 #include "komeda_format_caps.h"
 
-/** struct komeda_fb - entend drm_framebuffer with komeda attribute */
+/**
+ * struct komeda_fb - Entending drm_framebuffer with komeda attribute
+ */
 struct komeda_fb {
         /** @base: &drm_framebuffer */
         struct drm_framebuffer base;
-        /* @format_caps: &komeda_format_caps */
+        /**
+         * @format_caps:
+         * extends drm_format_info for komeda specific information
+         */
         const struct komeda_format_caps *format_caps;
         /** @aligned_w: aligned frame buffer width */
         u32 aligned_w;
diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_kms.h b/drivers/gpu/drm/arm/display/komeda/komeda_kms.h
index 7ec571d3c240..ac3d9209b4d9 100644
--- a/drivers/gpu/drm/arm/display/komeda/komeda_kms.h
+++ b/drivers/gpu/drm/arm/display/komeda/komeda_kms.h
@@ -15,7 +15,9 @@
 #include <video/videomode.h>
 #include <video/display_timing.h>
 
-/** struct komeda_plane - komeda instance of drm_plane */
+/**
+ * struct komeda_plane - komeda instance of drm_plane
+ */
 struct komeda_plane {
         /** @base: &drm_plane */
         struct drm_plane base;
@@ -71,11 +73,13 @@ struct komeda_crtc {
          */
         struct komeda_pipeline *slave;
 
-        /* this flip_done is for tracing the disable */
+        /** @disable_done: this flip_done is for tracing the disable */
         struct completion *disable_done;
 };
 
-/** struct komeda_crtc_state */
+/**
+ * struct komeda_crtc_state
+ */
 struct komeda_crtc_state {
         /** @base: &drm_crtc_state */
         struct drm_crtc_state base;
@@ -83,7 +87,15 @@ struct komeda_crtc_state {
         /* private properties */
 
         /* computed state which are used by validate/check */
+        /**
+         * @affected_pipes:
+         * the affected pipelines in once display instance
+         */
         u32 affected_pipes;
+        /**
+         * @active_pipes:
+         * the active pipelines in once display instance
+         */
         u32 active_pipes;
 };
 
diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h b/drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h
index 233e512319e8..b1f813a349a4 100644
--- a/drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h
+++ b/drivers/gpu/drm/arm/display/komeda/komeda_pipeline.h
@@ -90,32 +90,35 @@ struct komeda_component {
         u32 __iomem *reg;
         /** @id: component id */
         u32 id;
-        /** @hw_ic: component hw id,
-         *  which is initialized by chip and used by chip only
+        /**
+         * @hw_id: component hw id,
+         * which is initialized by chip and used by chip only
          */
         u32 hw_id;
 
         /**
          * @max_active_inputs:
-         * @max_active_outpus:
+         * @max_active_outputs:
          *
-         * maximum number of inputs/outputs that can be active in the same time
+         * maximum number of inputs/outputs that can be active at the same time
          * Note:
          * the number isn't the bit number of @supported_inputs or
          * @supported_outputs, but may be less than it, since component may not
          * support enabling all @supported_inputs/outputs at the same time.
          */
         u8 max_active_inputs;
+        /** @max_active_outputs: maximum number of outputs */
         u8 max_active_outputs;
         /**
          * @supported_inputs:
          * @supported_outputs:
          *
-         * bitmask of BIT(component->id) for the supported inputs/outputs
+         * bitmask of BIT(component->id) for the supported inputs/outputs,
          * describes the possibilities of how a component is linked into a
          * pipeline.
          */
         u32 supported_inputs;
+        /** @supported_outputs: bitmask of supported output componenet ids */
         u32 supported_outputs;
 
         /**
@@ -134,7 +137,8 @@ struct komeda_component {
 struct komeda_component_output {
         /** @component: indicate which component the data comes from */
         struct komeda_component *component;
-        /** @output_port:
+        /**
+         * @output_port:
          * the output port of the &komeda_component_output.component
          */
         u8 output_port;
@@ -150,11 +154,12 @@ struct komeda_component_output {
 struct komeda_component_state {
         /** @obj: tracking component_state by drm_atomic_state */
         struct drm_private_state obj;
+        /** @component: backpointer to the component */
         struct komeda_component *component;
         /**
          * @binding_user:
-         * currently bound user, the user can be crtc/plane/wb_conn, which is
-         * valid decided by @component and @inputs
+         * currently bound user, the user can be @crtc, @plane or @wb_conn,
+         * which is valid decided by @component and @inputs
          *
          * -  Layer: its user always is plane.
          * -  compiz/improc/timing_ctrlr: the user is crtc.
@@ -162,20 +167,24 @@ struct komeda_component_state {
          * -  scaler: plane when input is layer, wb_conn if input is compiz.
          */
         union {
+                /** @crtc: backpointer for user crtc */
                 struct drm_crtc *crtc;
+                /** @plane: backpointer for user plane */
                 struct drm_plane *plane;
+                /** @wb_conn: backpointer for user wb_connector  */
                 struct drm_connector *wb_conn;
                 void *binding_user;
         };
+
         /**
          * @active_inputs:
          *
          * active_inputs is bitmask of @inputs index
          *
-         * -  active_inputs = changed_active_inputs + unchanged_active_inputs
-         * -  affected_inputs = old->active_inputs + new->active_inputs;
+         * -  active_inputs = changed_active_inputs | unchanged_active_inputs
+         * -  affected_inputs = old->active_inputs | new->active_inputs;
          * -  disabling_inputs = affected_inputs ^ active_inputs;
-         * -  changed_inputs = disabling_inputs + changed_active_inputs;
+         * -  changed_inputs = disabling_inputs | changed_active_inputs;
          *
          * NOTE:
          * changed_inputs doesn't include all active_input but only
@@ -183,7 +192,9 @@ struct komeda_component_state {
          * level for dirty update.
          */
         u16 active_inputs;
+        /** @changed_active_inputs: bitmask of the changed @active_inputs */
         u16 changed_active_inputs;
+        /** @affected_inputs: bitmask for affected @inputs */
         u16 affected_inputs;
         /**
          * @inputs:
@@ -319,14 +330,23 @@ struct komeda_pipeline {
         int id;
         /** @avail_comps: available components mask of pipeline */
         u32 avail_comps;
+        /** @n_layers: the number of layer on @layers */
         int n_layers;
+        /** @layers: the pipeline layers */
         struct komeda_layer *layers[KOMEDA_PIPELINE_MAX_LAYERS];
+        /** @n_scalers: the number of scaler on @scalers */
         int n_scalers;
+        /** @scalers: the pipeline scalers */
         struct komeda_scaler *scalers[KOMEDA_PIPELINE_MAX_SCALERS];
+        /** @compiz: compositor */
         struct komeda_compiz *compiz;
+        /** @wb_layer: writeback layer */
         struct komeda_layer  *wb_layer;
+        /** @improc: post image processor */
         struct komeda_improc *improc;
+        /** @ctrlr: timing controller */
         struct komeda_timing_ctrlr *ctrlr;
+        /** @funcs: chip pipeline functions */
         struct komeda_pipeline_funcs *funcs; /* private pipeline functions */
 
         /** @of_node: pipeline dt node */
@@ -347,6 +367,7 @@ struct komeda_pipeline {
 struct komeda_pipeline_state {
         /** @obj: tracking pipeline_state by drm_atomic_state */
         struct drm_private_state obj;
+        /** @pipe: backpointer to the pipeline */
         struct komeda_pipeline *pipe;
         /** @crtc: currently bound crtc */
         struct drm_crtc *crtc;
diff --git a/drivers/gpu/drm/arm/display/komeda/komeda_plane.c b/drivers/gpu/drm/arm/display/komeda/komeda_plane.c
index ffcd3d08b5d3..46654f0be73d 100644
--- a/drivers/gpu/drm/arm/display/komeda/komeda_plane.c
+++ b/drivers/gpu/drm/arm/display/komeda/komeda_plane.c
@@ -39,6 +39,14 @@ komeda_plane_init_data_flow(struct drm_plane_state *st,
         return 0;
 }
 
+/**
+ * komeda_plane_atomic_check - build input data flow
+ * @plane: DRM plane
+ * @state: the plane state object
+ *
+ * RETURNS:
+ * Zero for success or -errno
+ */
 int komeda_plane_atomic_check(struct drm_plane *plane,
                               struct drm_plane_state *state)
 {