change system file

hc

2024-10-09 244b2c5ca8b14627e4a17755e5922221e121c771

 kernel/Documentation/doc-guide/kernel-doc.rst
..
..
@@ -77,7 +77,7 @@
77
77
    * Context: Describes whether the function can sleep, what locks it takes,
78
78
    *          releases, or expects to be held. It can extend over multiple
79
79
    *          lines.
80
-   * Return: Describe the return value of foobar.
80
+   * Return: Describe the return value of function_name.
81
81
    *
82
82
    * The return value description can also have multiple paragraphs, and should
83
83
    * be placed at the end of the comment block.
..
..
@@ -359,7 +359,7 @@
359
359
   ``monospaced font``.
360
360
 
361
361
   Useful if you need to use special characters that would otherwise have some
362
-  meaning either by kernel-doc script of by reStructuredText.
362
+  meaning either by kernel-doc script or by reStructuredText.
363
363
 
364
364
   This is particularly useful if you need to use things like ``%ph`` inside
365
365
   a function description.
..
..
@@ -387,22 +387,23 @@
387
387
 Cross-referencing from reStructuredText
388
388
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
389
389
 
390
-To cross-reference the functions and types defined in the kernel-doc comments
391
-from reStructuredText documents, please use the `Sphinx C Domain`_
392
-references. For example::
390
+No additional syntax is needed to cross-reference the functions and types
391
+defined in the kernel-doc comments from reStructuredText documents.
392
+Just end function names with ``()`` and write ``struct``, ``union``, ``enum``
393
+or ``typedef`` before types.
394
+For example::
393
395
 
394
-  See function :c:func:`foo` and struct/union/enum/typedef :c:type:`bar`.
396
+  See foo().
397
+  See struct foo.
398
+  See union bar.
399
+  See enum baz.
400
+  See typedef meh.
395
401
 
396
-While the type reference works with just the type name, without the
397
-struct/union/enum/typedef part in front, you may want to use::
402
+However, if you want custom text in the cross-reference link, that can be done
403
+through the following syntax::
398
404
 
399
-  See :c:type:`struct foo <foo>`.
400
-  See :c:type:`union bar <bar>`.
401
-  See :c:type:`enum baz <baz>`.
402
-  See :c:type:`typedef meh <meh>`.
403
-
404
-This will produce prettier links, and is in line with how kernel-doc does the
405
-cross-references.
405
+  See :c:func:`my custom link text for function foo <foo>`.
406
+  See :c:type:`my custom link text for struct bar <bar>`.
406
407
 
407
408
 For further details, please refer to the `Sphinx C Domain`_ documentation.
408
409
 
..
..
@@ -476,6 +477,30 @@
476
477
     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
477
478
        :internal:
478
479
 
480
+identifiers: *[ function/type ...]*
481
+  Include documentation for each *function* and *type* in *source*.
482
+  If no *function* is specified, the documentation for all functions
483
+  and types in the *source* will be included.
484
+
485
+  Examples::
486
+
487
+    .. kernel-doc:: lib/bitmap.c
488
+       :identifiers: bitmap_parselist bitmap_parselist_user
489
+
490
+    .. kernel-doc:: lib/idr.c
491
+       :identifiers:
492
+
493
+no-identifiers: *[ function/type ...]*
494
+  Exclude documentation for each *function* and *type* in *source*.
495
+
496
+  Example::
497
+
498
+    .. kernel-doc:: lib/bitmap.c
499
+       :no-identifiers: bitmap_parselist
500
+
501
+functions: *[ function/type ...]*
502
+  This is an alias of the 'identifiers' directive and deprecated.
503
+
479
504
 doc: *title*
480
505
   Include documentation for the ``DOC:`` paragraph identified by *title* in
481
506
   *source*. Spaces are allowed in *title*; do not quote the *title*. The *title*
..
..
@@ -487,19 +512,6 @@
487
512
 
488
513
     .. kernel-doc:: drivers/gpu/drm/i915/intel_audio.c
489
514
        :doc: High Definition Audio over HDMI and Display Port
490
-
491
-functions: *[ function ...]*
492
-  Include documentation for each *function* in *source*.
493
-  If no *function* if specified, the documentaion for all functions
494
-  and types in the *source* will be included.
495
-
496
-  Examples::
497
-
498
-    .. kernel-doc:: lib/bitmap.c
499
-       :functions: bitmap_parselist bitmap_parselist_user
500
-
501
-    .. kernel-doc:: lib/idr.c
502
-       :functions:
503
515
 
504
516
 Without options, the kernel-doc directive includes all documentation comments
505
517
 from the source file.
..
..
@@ -517,4 +529,17 @@
517
529
 If you just want to use kernel-doc to generate man pages you can do this
518
530
 from the kernel git tree::
519
531
 
520
-  $ scripts/kernel-doc -man $(git grep -l '/\*\*' -- :^Documentation :^tools) | scripts/split-man.pl /tmp/man
532
+  $ scripts/kernel-doc -man \
533
+    $(git grep -l '/\*\*' -- :^Documentation :^tools) \
534
+    | scripts/split-man.pl /tmp/man
535
+
536
+Some older versions of git do not support some of the variants of syntax for
537
+path exclusion.  One of the following commands may work for those versions::
538
+
539
+  $ scripts/kernel-doc -man \
540
+    $(git grep -l '/\*\*' -- . ':!Documentation' ':!tools') \
541
+    | scripts/split-man.pl /tmp/man
542
+
543
+  $ scripts/kernel-doc -man \
544
+    $(git grep -l '/\*\*' -- . ":(exclude)Documentation" ":(exclude)tools") \
545
+    | scripts/split-man.pl /tmp/man