kernel-doc (ed8348e23abce79780f3b679c74a48bcdc47c947) kernel-doc (93351d4196802b3ee01074d96df47b73716984ba)
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
3
4use warnings;
5use strict;
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##

--- 42 unchanged lines hidden (view full) ---

51The documentation comments are identified by "/**" opening comment mark. See
52Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
53
54Output format selection (mutually exclusive):
55 -man Output troff manual page format. This is the default.
56 -rst Output reStructuredText format.
57 -none Do not output documentation, only warnings.
58
1#!/usr/bin/env perl
2# SPDX-License-Identifier: GPL-2.0
3
4use warnings;
5use strict;
6
7## Copyright (c) 1998 Michael Zucchi, All Rights Reserved ##
8## Copyright (C) 2000, 1 Tim Waugh <twaugh@redhat.com> ##

--- 42 unchanged lines hidden (view full) ---

51The documentation comments are identified by "/**" opening comment mark. See
52Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.
53
54Output format selection (mutually exclusive):
55 -man Output troff manual page format. This is the default.
56 -rst Output reStructuredText format.
57 -none Do not output documentation, only warnings.
58
59Output format selection modifier (affects only ReST output):
60
61 -sphinx-version Use the ReST C domain dialect compatible with an
62 specific Sphinx Version.
63 If not specified, kernel-doc will auto-detect using
64 the sphinx-build version found on PATH.
65
59Output selection (mutually exclusive):
60 -export Only output documentation for symbols that have been
61 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
62 in any input FILE or -export-file FILE.
63 -internal Only output documentation for symbols that have NOT been
64 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
65 in any input FILE or -export-file FILE.
66 -function NAME Only output documentation for the given function(s)

--- 198 unchanged lines hidden (view full) ---

265my $blankline_rst = "\n";
266
267# read arguments
268if ($#ARGV == -1) {
269 usage();
270}
271
272my $kernelversion;
66Output selection (mutually exclusive):
67 -export Only output documentation for symbols that have been
68 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
69 in any input FILE or -export-file FILE.
70 -internal Only output documentation for symbols that have NOT been
71 exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()
72 in any input FILE or -export-file FILE.
73 -function NAME Only output documentation for the given function(s)

--- 198 unchanged lines hidden (view full) ---

272my $blankline_rst = "\n";
273
274# read arguments
275if ($#ARGV == -1) {
276 usage();
277}
278
279my $kernelversion;
273my $sphinx_major;
280my ($sphinx_major, $sphinx_minor, $sphinx_patch);
274
275my $dohighlight = "";
276
277my $verbose = 0;
278my $Werror = 0;
279my $output_mode = "rst";
280my $output_preformatted = 0;
281my $no_doc_sections = 0;

--- 170 unchanged lines hidden (view full) ---

452 } elsif (($cmd eq "h") || ($cmd eq "help")) {
453 usage();
454 } elsif ($cmd eq 'no-doc-sections') {
455 $no_doc_sections = 1;
456 } elsif ($cmd eq 'enable-lineno') {
457 $enable_lineno = 1;
458 } elsif ($cmd eq 'show-not-found') {
459 $show_not_found = 1; # A no-op but don't fail
281
282my $dohighlight = "";
283
284my $verbose = 0;
285my $Werror = 0;
286my $output_mode = "rst";
287my $output_preformatted = 0;
288my $no_doc_sections = 0;

--- 170 unchanged lines hidden (view full) ---

459 } elsif (($cmd eq "h") || ($cmd eq "help")) {
460 usage();
461 } elsif ($cmd eq 'no-doc-sections') {
462 $no_doc_sections = 1;
463 } elsif ($cmd eq 'enable-lineno') {
464 $enable_lineno = 1;
465 } elsif ($cmd eq 'show-not-found') {
466 $show_not_found = 1; # A no-op but don't fail
467 } elsif ($cmd eq "sphinx-version") {
468 my $ver_string = shift @ARGV;
469 if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {
470 $sphinx_major = $1;
471 if (defined($2)) {
472 $sphinx_minor = substr($2,1);
473 } else {
474 $sphinx_minor = 0;
475 }
476 if (defined($3)) {
477 $sphinx_patch = substr($3,1)
478 } else {
479 $sphinx_patch = 0;
480 }
481 } else {
482 die "Sphinx version should either major.minor or major.minor.patch format\n";
483 }
460 } else {
461 # Unknown argument
462 usage();
463 }
464}
465
466# continue execution near EOF;
467

--- 4 unchanged lines hidden (view full) ---

472 foreach(split(/:/, $ENV{PATH})) {
473 return "$_/$_[0]" if(-x "$_/$_[0]");
474 }
475}
476
477sub get_sphinx_version()
478{
479 my $ver;
484 } else {
485 # Unknown argument
486 usage();
487 }
488}
489
490# continue execution near EOF;
491

--- 4 unchanged lines hidden (view full) ---

496 foreach(split(/:/, $ENV{PATH})) {
497 return "$_/$_[0]" if(-x "$_/$_[0]");
498 }
499}
500
501sub get_sphinx_version()
502{
503 my $ver;
480 my $major = 1;
481
482 my $cmd = "sphinx-build";
483 if (!findprog($cmd)) {
484 my $cmd = "sphinx-build3";
504
505 my $cmd = "sphinx-build";
506 if (!findprog($cmd)) {
507 my $cmd = "sphinx-build3";
485 return $major if (!findprog($cmd));
508 if (!findprog($cmd)) {
509 $sphinx_major = 1;
510 $sphinx_minor = 2;
511 $sphinx_patch = 0;
512 printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n",
513 $sphinx_major, $sphinx_minor, $sphinx_patch;
514 return;
515 }
486 }
487
488 open IN, "$cmd --version 2>&1 |";
489 while (<IN>) {
490 if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
516 }
517
518 open IN, "$cmd --version 2>&1 |";
519 while (<IN>) {
520 if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {
491 $major=$1;
521 $sphinx_major = $1;
522 $sphinx_minor = $2;
523 $sphinx_patch = $3;
492 last;
493 }
494 # Sphinx 1.2.x uses a different format
495 if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
524 last;
525 }
526 # Sphinx 1.2.x uses a different format
527 if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {
496 $major=$1;
528 $sphinx_major = $1;
529 $sphinx_minor = $2;
530 $sphinx_patch = $3;
497 last;
498 }
499 }
500 close IN;
531 last;
532 }
533 }
534 close IN;
501
502 return $major;
503}
504
505# get kernel version from env
506sub get_kernel_version() {
507 my $version = 'unknown kernel version';
508
509 if (defined($ENV{'KERNELVERSION'})) {
510 $version = $ENV{'KERNELVERSION'};

--- 1817 unchanged lines hidden (view full) ---

2328 else {
2329 print STDERR "${file}:1: warning: no structured comments found\n";
2330 }
2331 }
2332 close IN_FILE;
2333}
2334
2335
535}
536
537# get kernel version from env
538sub get_kernel_version() {
539 my $version = 'unknown kernel version';
540
541 if (defined($ENV{'KERNELVERSION'})) {
542 $version = $ENV{'KERNELVERSION'};

--- 1817 unchanged lines hidden (view full) ---

2360 else {
2361 print STDERR "${file}:1: warning: no structured comments found\n";
2362 }
2363 }
2364 close IN_FILE;
2365}
2366
2367
2336$sphinx_major = get_sphinx_version();
2368if ($output_mode eq "rst") {
2369 get_sphinx_version() if (!$sphinx_major);
2370}
2371
2337$kernelversion = get_kernel_version();
2338
2339# generate a sequence of code that will splice in highlighting information
2340# using the s// operator.
2341for (my $k = 0; $k < @highlights; $k++) {
2342 my $pattern = $highlights[$k][0];
2343 my $result = $highlights[$k][1];
2344# print STDERR "scanning pattern:$pattern, highlight:($result)\n";

--- 44 unchanged lines hidden --- 		2372$kernelversion = get_kernel_version();
2373
2374# generate a sequence of code that will splice in highlighting information
2375# using the s// operator.
2376for (my $k = 0; $k < @highlights; $k++) {
2377 my $pattern = $highlights[$k][0];
2378 my $result = $highlights[$k][1];
2379# print STDERR "scanning pattern:$pattern, highlight:($result)\n";

--- 44 unchanged lines hidden ---