Merge branch 'mauro-vars' into docs-mw · tjh.dev/kernel@d07e085

+33 -15

Documentation/doc-guide/kernel-doc.rst

··· 174 174 Structure, union, and enumeration documentation 175 175 ----------------------------------------------- 176 176 177 - The general format of a struct, union, and enum kernel-doc comment is:: 177 + The general format of a ``struct``, ``union``, and ``enum`` kernel-doc 178 + comment is:: 178 179 179 180 /** 180 181 * struct struct_name - Brief description. ··· 188 187 */ 189 188 190 189 You can replace the ``struct`` in the above example with ``union`` or 191 - ``enum`` to describe unions or enums. ``member`` is used to mean struct 192 - and union member names as well as enumerations in an enum. 190 + ``enum`` to describe unions or enums. ``member`` is used to mean ``struct`` 191 + and ``union`` member names as well as enumerations in an ``enum``. 193 192 194 193 The brief description following the structure name may span multiple 195 194 lines, and ends with a member description, a blank comment line, or the ··· 202 201 as function parameters; they immediately succeed the short description 203 202 and may be multi-line. 204 203 205 - Inside a struct or union description, you can use the ``private:`` and 204 + Inside a ``struct`` or ``union`` description, you can use the ``private:`` and 206 205 ``public:`` comment tags. Structure fields that are inside a ``private:`` 207 206 area are not listed in the generated output documentation. 208 207 ··· 274 273 275 274 .. note:: 276 275 277 - #) When documenting nested structs or unions, if the struct/union ``foo`` 278 - is named, the member ``bar`` inside it should be documented as 276 + #) When documenting nested structs or unions, if the ``struct``/``union`` 277 + ``foo`` is named, the member ``bar`` inside it should be documented as 279 278 ``@foo.bar:`` 280 - #) When the nested struct/union is anonymous, the member ``bar`` in it 281 - should be documented as ``@bar:`` 279 + #) When the nested ``struct``/``union`` is anonymous, the member ``bar`` in 280 + it should be documented as ``@bar:`` 282 281 283 282 In-line member documentation comments 284 283 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ ··· 320 319 Typedef documentation 321 320 --------------------- 322 321 323 - The general format of a typedef kernel-doc comment is:: 322 + The general format of a ``typedef`` kernel-doc comment is:: 324 323 325 324 /** 326 325 * typedef type_name - Brief description. ··· 341 340 * Returns: Meaning of the return value. 342 341 */ 343 342 typedef void (*type_name)(struct v4l2_ctrl *arg1, void *arg2); 343 + 344 + Variables documentation 345 + ----------------------- 346 + 347 + The general format of a kernel-doc variable comment is:: 348 + 349 + /** 350 + * var var_name - Brief description. 351 + * 352 + * Description of the var_name variable. 353 + */ 354 + extern int var_name; 344 355 345 356 Object-like macro documentation 346 357 ------------------------------- ··· 445 432 Typedef reference. 446 433 447 434 ``&struct_name->member`` or ``&struct_name.member`` 448 - Structure or union member reference. The cross-reference will be to the struct 449 - or union definition, not the member directly. 435 + ``struct`` or ``union`` member reference. The cross-reference will be to the 436 + ``struct`` or ``union`` definition, not the member directly. 450 437 451 438 ``&name`` 452 439 A generic type reference. Prefer using the full reference described above ··· 475 462 476 463 For further details, please refer to the `Sphinx C Domain`_ documentation. 477 464 465 + .. note:: 466 + Variables aren't automatically cross referenced. For those, you need to 467 + explicitly add a C domain cross-reference. 468 + 478 469 Overview documentation comments 479 470 ------------------------------- 480 471 481 472 To facilitate having source code and comments close together, you can include 482 473 kernel-doc documentation blocks that are free-form comments instead of being 483 - kernel-doc for functions, structures, unions, enums, or typedefs. This could be 484 - used for something like a theory of operation for a driver or library code, for 485 - example. 474 + kernel-doc for functions, structures, unions, enums, typedefs or variables. 475 + This could be used for something like a theory of operation for a driver or 476 + library code, for example. 486 477 487 478 This is done by using a ``DOC:`` section keyword with a section title. 488 479 ··· 554 537 Include documentation for each *function* and *type* in *source*. 555 538 If no *function* is specified, the documentation for all functions 556 539 and types in the *source* will be included. 557 - *type* can be a struct, union, enum, or typedef identifier. 540 + *type* can be a ``struct``, ``union``, ``enum``, ``typedef`` or ``var`` 541 + identifier. 558 542 559 543 Examples:: 560 544

+15

include/media/v4l2-ioctl.h

··· 663 663 struct video_device; 664 664 665 665 /* names for fancy debug output */ 666 + 667 + /** 668 + * var v4l2_field_names - Helper array mapping ``V4L2_FIELD_*`` to strings. 669 + * 670 + * Specially when printing debug messages, it is interesting to output 671 + * the field order at the V4L2 buffers. This array associates all possible 672 + * values of field pix format from V4L2 API into a string. 673 + */ 666 674 extern const char *v4l2_field_names[]; 675 + 676 + /** 677 + * var v4l2_type_names - Helper array mapping ``V4L2_BUF_TYPE_*`` to strings. 678 + * 679 + * When printing debug messages, it is interesting to output the V4L2 buffer 680 + * type number with a name that represents its content. 681 + */ 667 682 extern const char *v4l2_type_names[]; 668 683 669 684 #ifdef CONFIG_COMPAT

+46

tools/lib/python/kdoc/kdoc_output.py

··· 199 199 self.out_enum(fname, name, args) 200 200 return self.data 201 201 202 + if dtype == "var": 203 + self.out_var(fname, name, args) 204 + return self.data 205 + 202 206 if dtype == "typedef": 203 207 self.out_typedef(fname, name, args) 204 208 return self.data ··· 230 226 231 227 def out_enum(self, fname, name, args): 232 228 """Outputs an enum""" 229 + 230 + def out_var(self, fname, name, args): 231 + """Outputs a variable""" 233 232 234 233 def out_typedef(self, fname, name, args): 235 234 """Outputs a typedef""" ··· 477 470 self.data += "\n" 478 471 479 472 self.lineprefix = oldprefix 473 + self.out_section(args) 474 + 475 + def out_var(self, fname, name, args): 476 + oldprefix = self.lineprefix 477 + ln = args.declaration_start_line 478 + full_proto = args.other_stuff["full_proto"] 479 + 480 + self.lineprefix = " " 481 + 482 + self.data += f"\n\n.. c:macro:: {name}\n\n{self.lineprefix}``{full_proto}``\n\n" 483 + 484 + self.print_lineno(ln) 485 + self.output_highlight(args.get('purpose', '')) 486 + self.data += "\n" 487 + 488 + if args.other_stuff["default_val"]: 489 + self.data += f'{self.lineprefix}**Initialization**\n\n' 490 + self.output_highlight(f'default: ``{args.other_stuff["default_val"]}``') 491 + 480 492 self.out_section(args) 481 493 482 494 def out_typedef(self, fname, name, args): ··· 794 768 parameter_name = KernRe(r'\[.*').sub('', parameter) 795 769 self.data += f'.IP "{parameter}" 12' + "\n" 796 770 self.output_highlight(args.parameterdescs.get(parameter_name, "")) 771 + 772 + for section, text in args.sections.items(): 773 + self.data += f'.SH "{section}"' + "\n" 774 + self.output_highlight(text) 775 + 776 + def out_var(self, fname, name, args): 777 + out_name = self.arg_name(args, name) 778 + full_proto = args.other_stuff["full_proto"] 779 + 780 + self.data += f'.TH "{self.modulename}" 9 "{out_name}" "{self.man_date}" "API Manual" LINUX' + "\n" 781 + 782 + self.data += ".SH NAME\n" 783 + self.data += f"{name} \\- {args['purpose']}\n" 784 + 785 + self.data += ".SH SYNOPSIS\n" 786 + self.data += f"{full_proto}\n" 787 + 788 + if args.other_stuff["default_val"]: 789 + self.data += f'.SH "Initialization"' + "\n" 790 + self.output_highlight(f'default: {args.other_stuff["default_val"]}') 797 791 798 792 for section, text in args.sections.items(): 799 793 self.data += f'.SH "{section}"' + "\n"

+78 -1

tools/lib/python/kdoc/kdoc_parser.py

··· 64 64 # Tests for the beginning of a kerneldoc block in its various forms. 65 65 # 66 66 doc_block = doc_com + KernRe(r'DOC:\s*(.*)?', cache=False) 67 - doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef)\b\s*(\w*)", cache = False) 67 + doc_begin_data = KernRe(r"^\s*\*?\s*(struct|union|enum|typedef|var)\b\s*(\w*)", cache = False) 68 68 doc_begin_func = KernRe(str(doc_com) + # initial " * ' 69 69 r"(?:\w+\s*\*\s*)?" + # type (not captured) 70 70 r'(?:define\s+)?' + # possible "define" (not captured) ··· 927 927 self.output_declaration('enum', declaration_name, 928 928 purpose=self.entry.declaration_purpose) 929 929 930 + def dump_var(self, ln, proto): 931 + """ 932 + Store variables that are part of kAPI. 933 + """ 934 + VAR_ATTRIBS = [ 935 + "extern", 936 + ] 937 + OPTIONAL_VAR_ATTR = "^(?:" + "|".join(VAR_ATTRIBS) + ")?" 938 + 939 + sub_prefixes = [ 940 + (KernRe(r"__read_mostly"), ""), 941 + (KernRe(r"__ro_after_init"), ""), 942 + (KernRe(r"(?://.*)$"), ""), 943 + (KernRe(r"(?:/\*.*\*/)"), ""), 944 + (KernRe(r";$"), ""), 945 + (KernRe(r"=.*"), ""), 946 + ] 947 + 948 + # 949 + # Store the full prototype before modifying it 950 + # 951 + full_proto = proto 952 + declaration_name = None 953 + 954 + # 955 + # Handle macro definitions 956 + # 957 + macro_prefixes = [ 958 + KernRe(r"DEFINE_[\w_]+\s*$([\w_]+)$"), 959 + ] 960 + 961 + for r in macro_prefixes: 962 + match = r.search(proto) 963 + if match: 964 + declaration_name = match.group(1) 965 + break 966 + 967 + # 968 + # Drop comments and macros to have a pure C prototype 969 + # 970 + if not declaration_name: 971 + for r, sub in sub_prefixes: 972 + proto = r.sub(sub, proto) 973 + 974 + proto = proto.rstrip() 975 + 976 + # 977 + # Variable name is at the end of the declaration 978 + # 979 + 980 + default_val = None 981 + 982 + r= KernRe(OPTIONAL_VAR_ATTR + r"\w.*\s+(?:\*+)?([\w_]+)\s*[\d\]\[]*\s*(=.*)?") 983 + if r.match(proto): 984 + if not declaration_name: 985 + declaration_name = r.group(1) 986 + 987 + default_val = r.group(2) 988 + else: 989 + r= KernRe(OPTIONAL_VAR_ATTR + r"(?:\w.*)?\s+(?:\*+)?(?:[\w_]+)\s*[\d\]\[]*\s*(=.*)?") 990 + if r.match(proto): 991 + default_val = r.group(1) 992 + 993 + if not declaration_name: 994 + self.emit_msg(ln,f"{proto}: can't parse variable") 995 + return 996 + 997 + if default_val: 998 + default_val = default_val.lstrip("=").strip() 999 + 1000 + self.output_declaration("var", declaration_name, 1001 + full_proto=full_proto, 1002 + default_val=default_val, 1003 + purpose=self.entry.declaration_purpose) 1004 + 930 1005 def dump_declaration(self, ln, prototype): 931 1006 """ 932 1007 Stores a data declaration inside self.entries array. ··· 1013 938 self.dump_typedef(ln, prototype) 1014 939 elif self.entry.decl_type in ["union", "struct"]: 1015 940 self.dump_struct(ln, prototype) 941 + elif self.entry.decl_type == "var": 942 + self.dump_var(ln, prototype) 1016 943 else: 1017 944 # This would be a bug 1018 945 self.emit_message(ln, f'Unknown declaration type: {self.entry.decl_type}')

Configure Feed

Configure Feed