On Mon, Feb 22, 2021 at 6:27 PM Aditya <yashsri421@xxxxxxxxx> wrote:
>
> Hi Jonathan, Lukas
>
> While investigating "error: Cannot parse struct or union!", I
> discovered few more patterns causing this error:
> 1) A large part of this error(~80%) occurs due to the presence of one
> or more lines(such as '#define' lines) between commented code and
> struct declaration.
>
> For e.g., in include/linux/platform_data/apds990x.h:
>
> /**
> * struct apds990x_chip_factors - defines effect of the cover window
> * @ga: Total glass attenuation
> * @cf1: clear channel factor 1 for raw to lux conversion
> * @irf1: IR channel factor 1 for raw to lux conversion
> * @cf2: clear channel factor 2 for raw to lux conversion
> * @irf2: IR channel factor 2 for raw to lux conversion
> * @df: device factor for conversion formulas
> *
> * Structure for tuning ALS calculation to match with environment.
> * Values depend on the material above the sensor and the sensor
> * itself. If the GA is zero, driver will use uncovered sensor default
> values
> * format: decimal value * APDS_PARAM_SCALE except df which is plain
> integer.
> */
> #define APDS_PARAM_SCALE 4096
> struct apds990x_chip_factors {
> int ga;
> int cf1;
> int irf1;
> int cf2;
> int irf2;
> int df;
> };
>
>
Aditya, I independently made a similar observation and noted this
issue in my personal notes, which will serve for a cleanup patch
series, as follows:
"SKIP DEFINITIONS" Feature:
The kernel-doc should proceed the code, and the required definition of
data structures should stay close to the function in between the
kernel-doc comment and the function definition.
Let kernel-doc know to skip certain definitions; the actual definition
documented will follow directly after the skipped definitions.
E.g.,
include/linux/cgroup.h:450: task_css_set_check: SKIP DEFINITIONS
(struct mutex cgroup_mutex; spinlock_t css_set_lock)
include/linux/hid-sensor-hub.h:174:
sensor_hub_input_attr_get_raw_value: SKIP DEFINITIONS (enum
sensor_hub_read_flags)
I have not thought about a good syntax for that:
maybe something like:
/**
* foo - description
*
* @arg: description
*
* ::skip: struct bar, enum blub, define MACRO
*/
where "::" serves as some annotation to instruct kernel-doc
> 2) If struct does not contain any members, for e.g., in
> include/linux/xz.h:
>
> /**
> * struct xz_dec - Opaque type to hold the XZ decoder state
> */
> struct xz_dec;
>
> Here, it causes error as the curly braces and members expected by the
> regex, are absent.
> This kind of use has also been made in include/linux/zstd.h:
>
> /**
> * struct ZSTD_DDict - a digested dictionary to be used for decompression
> */
> typedef struct ZSTD_DDict_s ZSTD_DDict;
>
>
> 3) Different Syntax than expected. For e.g.:
> a) struct xyz struct_name {} syntax. This syntax has been used in
> arch/arm/mach-omap2/omap_hwmod_common_data.c file
> b) "static __maybe_unused const struct st_sensors_platform_data
> default_press_pdata = {" in drivers/iio/pressure/st_pressure.h.
> This kind of syntax has also been used in
> drivers/iio/accel/st_accel.h, and drivers/iio/gyro/st_gyro.h
>
> I wanted to take your opinion if we should extend support for any of
> these syntax, causing the error. If not, perhaps we can make the
> documentation a bit clear, atleast for (1), which causes most of these
> errors; so as to not include any lines between comment and struct
> declaration.
>
> What do you think?
>
I certainly appreciate it if you could work on that SKIP_DEFINITION
feature, once we agreed on some first syntax for this feature.
Lukas
