diff --git a/Documentation/doc-guide/kernel-doc.rst b/Documentation/doc-guide/kernel-doc.rst index fd89a6d56ea9..0de0e344e10d 100644 --- a/Documentation/doc-guide/kernel-doc.rst +++ b/Documentation/doc-guide/kernel-doc.rst @@ -174,7 +174,8 @@ named ``Return`` (or ``Returns``). Structure, union, and enumeration documentation ----------------------------------------------- -The general format of a struct, union, and enum kernel-doc comment is:: +The general format of a ``struct``, ``union``, and ``enum`` kernel-doc +comment is:: /** * struct struct_name - Brief description. @@ -187,8 +188,8 @@ The general format of a struct, union, and enum kernel-doc comment is:: */ You can replace the ``struct`` in the above example with ``union`` or -``enum`` to describe unions or enums. ``member`` is used to mean struct -and union member names as well as enumerations in an enum. +``enum`` to describe unions or enums. ``member`` is used to mean ``struct`` +and ``union`` member names as well as enumerations in an ``enum``. The brief description following the structure name may span multiple lines, and ends with a member description, a blank comment line, or the @@ -201,7 +202,7 @@ Members of structs, unions and enums should be documented the same way as function parameters; they immediately succeed the short description and may be multi-line. -Inside a struct or union description, you can use the ``private:`` and +Inside a ``struct`` or ``union`` description, you can use the ``private:`` and ``public:`` comment tags. Structure fields that are inside a ``private:`` area are not listed in the generated output documentation. @@ -273,11 +274,11 @@ It is possible to document nested structs and unions, like:: .. note:: - #) When documenting nested structs or unions, if the struct/union ``foo`` - is named, the member ``bar`` inside it should be documented as + #) When documenting nested structs or unions, if the ``struct``/``union`` + ``foo`` is named, the member ``bar`` inside it should be documented as ``@foo.bar:`` - #) When the nested struct/union is anonymous, the member ``bar`` in it - should be documented as ``@bar:`` + #) When the nested ``struct``/``union`` is anonymous, the member ``bar`` in + it should be documented as ``@bar:`` In-line member documentation comments ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -319,7 +320,7 @@ on a line of their own, like all other kernel-doc comments:: Typedef documentation --------------------- -The general format of a typedef kernel-doc comment is:: +The general format of a ``typedef`` kernel-doc comment is:: /** * typedef type_name - Brief description. @@ -341,6 +342,18 @@ Typedefs with function prototypes can also be documented:: */ typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); +Variables documentation +----------------------- + +The general format of a kernel-doc variable comment is:: + + /** + * var var_name - Brief description. + * + * Description of the var_name variable. + */ + extern int var_name; + Object-like macro documentation ------------------------------- @@ -432,8 +445,8 @@ Domain`_ references. Typedef reference. ``&struct_name->member`` or ``&struct_name.member`` - Structure or union member reference. The cross-reference will be to the struct - or union definition, not the member directly. + ``struct`` or ``union`` member reference. The cross-reference will be to the + ``struct`` or ``union`` definition, not the member directly. ``&name`` A generic type reference. Prefer using the full reference described above @@ -462,14 +475,18 @@ through the following syntax:: For further details, please refer to the `Sphinx C Domain`_ documentation. +.. note:: + Variables aren't automatically cross referenced. For those, you need to + explicitly add a C domain cross-reference. + Overview documentation comments ------------------------------- To facilitate having source code and comments close together, you can include kernel-doc documentation blocks that are free-form comments instead of being -kernel-doc for functions, structures, unions, enums, or typedefs. This could be -used for something like a theory of operation for a driver or library code, for -example. +kernel-doc for functions, structures, unions, enums, typedefs or variables. +This could be used for something like a theory of operation for a driver or +library code, for example. This is done by using a ``DOC:`` section keyword with a section title. @@ -537,7 +554,8 @@ identifiers: *[ function/type ...]* Include documentation for each *function* and *type* in *source*. If no *function* is specified, the documentation for all functions and types in the *source* will be included. - *type* can be a struct, union, enum, or typedef identifier. + *type* can be a ``struct``, ``union``, ``enum``, ``typedef`` or ``var`` + identifier. Examples:: diff --git a/include/media/v4l2-ioctl.h b/include/media/v4l2-ioctl.h index 6f7a58350441..54c83b18d555 100644 --- a/include/media/v4l2-ioctl.h +++ b/include/media/v4l2-ioctl.h @@ -663,7 +663,22 @@ void v4l_printk_ioctl(const char *prefix, unsigned int cmd); struct video_device; /* names for fancy debug output */ + +/** + * var v4l2_field_names - Helper array mapping ``V4L2_FIELD_*`` to strings. + * + * Specially when printing debug messages, it is interesting to output + * the field order at the V4L2 buffers. This array associates all possible + * values of field pix format from V4L2 API into a string. + */ extern const char *v4l2_field_names[]; + +/** + * var v4l2_type_names - Helper array mapping ``V4L2_BUF_TYPE_*`` to strings. + * + * When printing debug messages, it is interesting to output the V4L2 buffer + * type number with a name that represents its content. + */ extern const char *v4l2_type_names[]; #ifdef CONFIG_COMPAT diff --git a/tools/lib/python/kdoc/kdoc_output.py b/tools/lib/python/kdoc/kdoc_output.py index b1aaa7fc3604..d2bf94275d65 100644 --- a/tools/lib/python/kdoc/kdoc_output.py +++ b/tools/lib/python/kdoc/kdoc_output.py @@ -199,6 +199,10 @@ class OutputFormat: self.out_enum(fname, name, args) return self.data + if dtype == "var": + self.out_var(fname, name, args) + return self.data + if dtype == "typedef": self.out_typedef(fname, name, args) return self.data @@ -227,6 +231,9 @@ class OutputFormat: def out_enum(self, fname, name, args): """Outputs an enum""" + def out_var(self, fname, name, args): + """Outputs a variable""" + def out_typedef(self, fname, name, args): """Outputs a typedef""" @@ -472,6 +479,25 @@ class RestFormat(OutputFormat): self.lineprefix = oldprefix self.out_section(args) + def out_var(self, fname, name, args): + oldprefix = self.lineprefix + ln = args.declaration_start_line + full_proto = args.other_stuff["full_proto"] + + self.lineprefix = " " + + self.data += f"\n\n.. c:macro:: {name}\n\n{self.lineprefix}``{full_proto}``\n\n" + + self.print_lineno(ln) + self.output_highlight(args.get('purpose', '')) + self.data += "\n" + + if args.other_stuff["default_val"]: + self.data += f'{self.lineprefix}**Initialization**\n\n' + self.output_highlight(f'default: ``{args.other_stuff["default_val"]}``') + + self.out_section(args) + def out_typedef(self, fname, name, args): oldprefix = self.lineprefix @@ -773,6 +799,26 @@ class ManFormat(OutputFormat): self.data += f'.SH "{section}"' + "\n" self.output_highlight(text) + def out_var(self, fname, name, args): + out_name = self.arg_name(args, name) + full_proto = args.other_stuff["full_proto"] + + self.data += f'.TH "{self.modulename}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "\n" + + self.data += ".SH NAME\n" + self.data += f"{name} \\- {args['purpose']}\n" + + self.data += ".SH SYNOPSIS\n" + self.data += f"{full_proto}\n" + + if args.other_stuff["default_val"]: + self.data += f'.SH "Initialization"' + "\n" + self.output_highlight(f'default: {args.other_stuff["default_val"]}') + + for section, text in args.sections.items(): + self.data += f'.SH "{section}"' + "\n" + self.output_highlight(text) + def out_typedef(self, fname, name, args): module = self.modulename purpose = args.get('purpose') diff --git a/tools/lib/python/kdoc/kdoc_parser.py b/tools/lib/python/kdoc/kdoc_parser.py index 500aafc50032..e137bd9a7dac 100644 --- a/tools/lib/python/kdoc/kdoc_parser.py +++ b/tools/lib/python/kdoc/kdoc_parser.py @@ -64,7 +64,7 @@ type_param = KernRe(r"@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)", cache=False) # Tests for the beginning of a kerneldoc block in its various forms. # doc_block = doc_com + KernRe(r'DOC:\s*(.*)?', cache=False) -doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\b\s*(\w*)", cache = False) +doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef|var)\b\s*(\w*)", cache = False) doc_begin_func = KernRe(str(doc_com) + # initial " * ' r"(?:\w+\s*\*\s*)?" + # type (not captured) r'(?:define\s+)?' + # possible "define" (not captured) @@ -927,6 +927,81 @@ class KernelDoc: self.output_declaration('enum', declaration_name, purpose=self.entry.declaration_purpose) + def dump_var(self, ln, proto): + """ + Store variables that are part of kAPI. + """ + VAR_ATTRIBS = [ + "extern", + ] + OPTIONAL_VAR_ATTR = "^(?:" + "|".join(VAR_ATTRIBS) + ")?" + + sub_prefixes = [ + (KernRe(r"__read_mostly"), ""), + (KernRe(r"__ro_after_init"), ""), + (KernRe(r"(?://.*)$"), ""), + (KernRe(r"(?:/\*.*\*/)"), ""), + (KernRe(r";$"), ""), + (KernRe(r"=.*"), ""), + ] + + # + # Store the full prototype before modifying it + # + full_proto = proto + declaration_name = None + + # + # Handle macro definitions + # + macro_prefixes = [ + KernRe(r"DEFINE_[\w_]+\s*\(([\w_]+)\)"), + ] + + for r in macro_prefixes: + match = r.search(proto) + if match: + declaration_name = match.group(1) + break + + # + # Drop comments and macros to have a pure C prototype + # + if not declaration_name: + for r, sub in sub_prefixes: + proto = r.sub(sub, proto) + + proto = proto.rstrip() + + # + # Variable name is at the end of the declaration + # + + default_val = None + + r= KernRe(OPTIONAL_VAR_ATTR + r"\w.*\s+(?:\*+)?([\w_]+)\s*[\d\]\[]*\s*(=.*)?") + if r.match(proto): + if not declaration_name: + declaration_name = r.group(1) + + default_val = r.group(2) + else: + r= KernRe(OPTIONAL_VAR_ATTR + r"(?:\w.*)?\s+(?:\*+)?(?:[\w_]+)\s*[\d\]\[]*\s*(=.*)?") + if r.match(proto): + default_val = r.group(1) + + if not declaration_name: + self.emit_msg(ln,f"{proto}: can't parse variable") + return + + if default_val: + default_val = default_val.lstrip("=").strip() + + self.output_declaration("var", declaration_name, + full_proto=full_proto, + default_val=default_val, + purpose=self.entry.declaration_purpose) + def dump_declaration(self, ln, prototype): """ Stores a data declaration inside self.entries array. @@ -938,6 +1013,8 @@ class KernelDoc: self.dump_typedef(ln, prototype) elif self.entry.decl_type in ["union", "struct"]: self.dump_struct(ln, prototype) + elif self.entry.decl_type == "var": + self.dump_var(ln, prototype) else: # This would be a bug self.emit_message(ln, f'Unknown declaration type: {self.entry.decl_type}')