kernel-doc: rename the kernel-doc directive 'functions' to 'identifiers'

The 'functions' directive is not only for functions, but also works for
structs/unions. So the name is misleading. This patch renames it to
'identifiers', which specific the functions/types to be included in
documentation. We keep the old name as an alias of the new one before
all documentation are updated.

Signed-off-by: Changbin Du <changbin.du@gmail.com>
Signed-off-by: Jonathan Corbet <corbet@lwn.net>

authored by

Changbin Du and committed by

Jonathan Corbet 6 years ago 36bc683d e80d8938

+27 -19

2 changed files

expand all

Documentation

doc-guide

kernel-doc.rst

sphinx

kerneldoc.py

+16 -13

Documentation/doc-guide/kernel-doc.rst

··· 476 476 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 477 477 :internal: 478 478 479 + identifiers: *[ function/type ...]* 480 + Include documentation for each *function* and *type* in *source*. 481 + If no *function* is specified, the documentation for all functions 482 + and types in the *source* will be included. 483 + 484 + Examples:: 485 + 486 + .. kernel-doc:: lib/bitmap.c 487 + :identifiers: bitmap_parselist bitmap_parselist_user 488 + 489 + .. kernel-doc:: lib/idr.c 490 + :identifiers: 491 + 492 + functions: *[ function/type ...]* 493 + This is an alias of the 'identifiers' directive and deprecated. 494 + 479 495 doc: *title* 480 496 Include documentation for the ``DOC:`` paragraph identified by *title* in 481 497 *source*. Spaces are allowed in *title*; do not quote the *title*. The *title* ··· 503 487 504 488 .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c 505 489 :doc: High Definition Audio over HDMI and Display Port 506 - 507 - functions: *[ function ...]* 508 - Include documentation for each *function* in *source*. 509 - If no *function* is specified, the documentation for all functions 510 - and types in the *source* will be included. 511 - 512 - Examples:: 513 - 514 - .. kernel-doc:: lib/bitmap.c 515 - :functions: bitmap_parselist bitmap_parselist_user 516 - 517 - .. kernel-doc:: lib/idr.c 518 - :functions: 519 490 520 491 Without options, the kernel-doc directive includes all documentation comments 521 492 from the source file.

+11 -6

Documentation/sphinx/kerneldoc.py

··· 59 59 optional_arguments = 4 60 60 option_spec = { 61 61 'doc': directives.unchanged_required, 62 - 'functions': directives.unchanged, 63 62 'export': directives.unchanged, 64 63 'internal': directives.unchanged, 64 + 'identifiers': directives.unchanged, 65 + 'functions': directives.unchanged, 65 66 } 66 67 has_content = False 67 68 ··· 78 77 79 78 tab_width = self.options.get('tab-width', self.state.document.settings.tab_width) 80 79 80 + # 'function' is an alias of 'identifiers' 81 + if 'functions' in self.options: 82 + self.options['identifiers'] = self.options.get('functions') 83 + 81 84 # FIXME: make this nicer and more robust against errors 82 85 if 'export' in self.options: 83 86 cmd += ['-export'] ··· 91 86 export_file_patterns = str(self.options.get('internal')).split() 92 87 elif 'doc' in self.options: 93 88 cmd += ['-function', str(self.options.get('doc'))] 94 - elif 'functions' in self.options: 95 - functions = self.options.get('functions').split() 96 - if functions: 97 - for f in functions: 98 - cmd += ['-function', f] 89 + elif 'identifiers' in self.options: 90 + identifiers = self.options.get('identifiers').split() 91 + if identifiers: 92 + for i in identifiers: 93 + cmd += ['-function', i] 99 94 else: 100 95 cmd += ['-no-doc-sections'] 101 96

Configure Feed

Configure Feed