linux/scripts/kernel-doc at master · linuxkit/linux · GitHub

History

executable file

2515 lines (2230 loc) · 69 KB

Raw

100

101

102

103

104

105

106

107

108

109

110

111

112

113

114

115

116

117

118

119

120

121

122

123

124

125

126

127

128

129

130

131

132

133

134

135

136

137

138

139

140

141

142

143

144

145

146

147

148

149

150

151

152

153

154

155

156

157

158

159

160

161

162

163

164

165

166

167

168

169

170

171

172

173

174

175

176

177

178

179

180

181

182

183

184

185

186

187

188

189

190

191

192

193

194

195

196

197

198

199

200

201

202

203

204

205

206

207

208

209

210

211

212

213

214

215

216

217

218

219

220

221

222

223

224

225

226

227

228

229

230

231

232

233

234

235

236

237

238

239

240

241

242

243

244

245

246

247

248

249

250

251

252

253

254

255

256

257

258

259

260

261

262

263

264

265

266

267

268

269

270

271

272

273

274

275

276

277

278

279

280

281

282

283

284

285

286

287

288

289

290

291

292

293

294

295

296

297

298

299

300

301

302

303

304

305

306

307

308

309

310

311

312

313

314

315

316

317

318

319

320

321

322

323

324

325

326

327

328

329

330

331

332

333

334

335

336

337

338

339

340

341

342

343

344

345

346

347

348

349

350

351

352

353

354

355

356

357

358

359

360

361

362

363

364

365

366

367

368

369

370

371

372

373

374

375

376

377

378

379

380

381

382

383

384

385

386

387

388

389

390

391

392

393

394

395

396

397

398

399

400

401

402

403

404

405

406

407

408

409

410

411

412

413

414

415

416

417

418

419

420

421

422

423

424

425

426

427

428

429

430

431

432

433

434

435

436

437

438

439

440

441

442

443

444

445

446

447

448

449

450

451

452

453

454

455

456

457

458

459

460

461

462

463

464

465

466

467

468

469

470

471

472

473

474

475

476

477

478

479

480

481

482

483

484

485

486

487

488

489

490

491

492

493

494

495

496

497

498

499

500

501

502

503

504

505

506

507

508

509

510

511

512

513

514

515

516

517

518

519

520

521

522

523

524

525

526

527

528

529

530

531

532

533

534

535

536

537

538

539

540

541

542

543

544

545

546

547

548

549

550

551

552

553

554

555

556

557

558

559

560

561

562

563

564

565

566

567

568

569

570

571

572

573

574

575

576

577

578

579

580

581

582

583

584

585

586

587

588

589

590

591

592

593

594

595

596

597

598

599

600

601

602

603

604

605

606

607

608

609

610

611

612

613

614

615

616

617

618

619

620

621

622

623

624

625

626

627

628

629

630

631

632

633

634

635

636

637

638

639

640

641

642

643

644

645

646

647

648

649

650

651

652

653

654

655

656

657

658

659

660

661

662

663

664

665

666

667

668

669

670

671

672

673

674

675

676

677

678

679

680

681

682

683

684

685

686

687

688

689

690

691

692

693

694

695

696

697

698

699

700

701

702

703

704

705

706

707

708

709

710

711

712

713

714

715

716

717

718

719

720

721

722

723

724

725

726

727

728

729

730

731

732

733

734

735

736

737

738

739

740

741

742

743

744

745

746

747

748

749

750

751

752

753

754

755

756

757

758

759

760

761

762

763

764

765

766

767

768

769

770

771

772

773

774

775

776

777

778

779

780

781

782

783

784

785

786

787

788

789

790

791

792

793

794

795

796

797

798

799

800

801

802

803

804

805

806

807

808

809

810

811

812

813

814

815

816

817

818

819

820

821

822

823

824

825

826

827

828

829

830

831

832

833

834

835

836

837

838

839

840

841

842

843

844

845

846

847

848

849

850

851

852

853

854

855

856

857

858

859

860

861

862

863

864

865

866

867

868

869

870

871

872

873

874

875

876

877

878

879

880

881

882

883

884

885

886

887

888

889

890

891

892

893

894

895

896

897

898

899

900

901

902

903

904

905

906

907

908

909

910

911

912

913

914

915

916

917

918

919

920

921

922

923

924

925

926

927

928

929

930

931

932

933

934

935

936

937

938

939

940

941

942

943

944

945

946

947

948

949

950

951

952

953

954

955

956

957

958

959

960

961

962

963

964

965

966

967

968

969

970

971

972

973

974

975

976

977

978

979

980

981

982

983

984

985

986

987

988

989

990

991

992

993

994

995

996

997

998

999

1000

#!/usr/bin/env perl

# SPDX-License-Identifier: GPL-2.0

use warnings;

use strict;

## ##

## #define enhancements by Armin Kuster <akuster@mvista.com> ##

## ##

## This software falls under the GNU General Public License. ##

## Please read the COPYING file for more information ##

# 18/01/2001 - Cleanups

# Functions prototyped as foo(void) same as foo()

# Stop eval'ing where we don't need to.

# -- huggie@earth.li

# 27/06/2001 - Allowed whitespace after initial "/**" and

# allowed comments before function declarations.

# -- Christian Kreibich <ck@whoop.org>

# Still to do:

# - add perldoc documentation

# - Look more closely at some of the scarier bits :)

# 26/05/2001 - Support for separate source and object trees.

# Return error code.

# Keith Owens <kaos@ocs.com.au>

# 23/09/2001 - Added support for typedefs, structs, enums and unions

# Support for Context section; can be terminated using empty line

# Small fixes (like spaces vs. \s in regex)

# -- Tim Jansen <tim@tjansen.de>

# 25/07/2012 - Added support for HTML5

# -- Dan Luedtke <mail@danrl.de>

sub usage {

my $message = <<"EOF";

Usage: $0 [OPTION ...] FILE ...

Read C language source or header FILEs, extract embedded documentation comments,

and print formatted documentation to standard output.

The documentation comments are identified by "/**" opening comment mark. See

Documentation/doc-guide/kernel-doc.rst for the documentation comment syntax.

Output format selection (mutually exclusive):

-man Output troff manual page format. This is the default.

-rst Output reStructuredText format.

-none Do not output documentation, only warnings.

Output format selection modifier (affects only ReST output):

-sphinx-version Use the ReST C domain dialect compatible with an

specific Sphinx Version.

If not specified, kernel-doc will auto-detect using

the sphinx-build version found on PATH.

Output selection (mutually exclusive):

-export Only output documentation for symbols that have been

exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()

in any input FILE or -export-file FILE.

-internal Only output documentation for symbols that have NOT been

exported using EXPORT_SYMBOL() or EXPORT_SYMBOL_GPL()

in any input FILE or -export-file FILE.

-function NAME Only output documentation for the given function(s)

or DOC: section title(s). All other functions and DOC:

sections are ignored. May be specified multiple times.

-nosymbol NAME Exclude the specified symbols from the output

documentation. May be specified multiple times.

Output selection modifiers:

-no-doc-sections Do not output DOC: sections.

-enable-lineno Enable output of #define LINENO lines. Only works with

reStructuredText format.

-export-file FILE Specify an additional FILE in which to look for

EXPORT_SYMBOL() and EXPORT_SYMBOL_GPL(). To be used with

-export or -internal. May be specified multiple times.

Other parameters:

-v Verbose output, more warnings and other information.

-h Print this help.

-Werror Treat warnings as errors.

EOF

print $message;

exit 1;

}

# format of comments.

# In the following table, (...)? signifies optional structure.

# (...)* signifies 0 or more structure elements

# /**

# * function_name(:)? (- short description)?

# (* @parameterx: (description of parameter x)?)*

# (* a blank line)?

# * (Description:)? (Description of function)?

# * (section header: (section description)? )*

# (*)?*/

# So .. the trivial example would be:

# /**

# * my_function

# */

# If the Description: header tag is omitted, then there must be a blank line

# after the last parameter specification.

# e.g.

# /**

# * my_function - does my stuff

# * @my_arg: its mine damnit

# *

# * Does my stuff explained.

# */

# or, could also use:

# /**

# * my_function - does my stuff

# * @my_arg: its mine damnit

# * Description: Does my stuff explained.

# */

# etc.

# Besides functions you can also write documentation for structs, unions,

# enums and typedefs. Instead of the function name you must write the name

# of the declaration; the struct/union/enum/typedef must always precede

# the name. Nesting of declarations is not supported.

# Use the argument mechanism to document members or constants.

# e.g.

# /**

# * struct my_struct - short description

# * @a: first member

# * @b: second member

# *

# * Longer description

# */

# struct my_struct {

# int a;

# int b;

# /* private: */

# int c;

# };

# All descriptions can be multiline, except the short function description.

# For really longs structs, you can also describe arguments inside the

# body of the struct.

# eg.

# /**

# * struct my_struct - short description

# * @a: first member

# * @b: second member

# *

# * Longer description

# */

# struct my_struct {

# int a;

# int b;

# /**

# * @c: This is longer description of C

# *

# * You can use paragraphs to describe arguments

# * using this method.

# */

# int c;

# };

# This should be use only for struct/enum members.

# You can also add additional sections. When documenting kernel functions you

# should document the "Context:" of the function, e.g. whether the functions

# can be called form interrupts. Unlike other sections you can end it with an

# empty line.

# A non-void function should have a "Return:" section describing the return

# value(s).

# Example-sections should contain the string EXAMPLE so that they are marked

# appropriately in DocBook.

# Example:

# /**

# * user_function - function that can only be called in user context

# * @a: some argument

# * Context: !in_interrupt()

# *

# * Some description

# * Example:

# * user_function(22);

# */

# ...

# All descriptive text is further processed, scanning for the following special

# patterns, which are highlighted appropriately.

# 'funcname()' - function

# '$ENVVAR' - environmental variable

# '&struct_name' - name of a structure (up to two words including 'struct')

# '&struct_name.member' - name of a structure member

# '@parameter' - name of a parameter

# '%CONST' - name of a constant.

# '``LITERAL``' - literal string without any spaces on it.

## init lots of data

my $errors = 0;

my $warnings = 0;

my $anon_struct_union = 0;

# match expressions used to find embedded type information

my $type_constant = '\b``([^\`]+)``\b';

my $type_constant2 = '\%([-_\w]+)';

my $type_func = '(\w+)';

my $type_param = '\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';

my $type_param_ref = '([\!]?)\@(\w*((\.\w+)|(->\w+))*(\.\.\.)?)';

my $type_fp_param = '\@(\w+)'; # Special RST handling for func ptr params

my $type_fp_param2 = '\@(\w+->\S+)'; # Special RST handling for structs with func ptr params

my $type_env = '(\$\w+)';

my $type_enum = '\&(enum\s*([_\w]+))';

my $type_struct = '\&(struct\s*([_\w]+))';

my $type_typedef = '\&(typedef\s*([_\w]+))';

my $type_union = '\&(union\s*([_\w]+))';

my $type_member = '\&([_\w]+)(\.|->)([_\w]+)';

my $type_fallback = '\&([_\w]+)';

my $type_member_func = $type_member . '';

# Output conversion substitutions.

# One for each output format

# these are pretty rough

my @highlights_man = (

[$type_constant, "\$1"],

[$type_constant2, "\$1"],

[$type_func, "\\\\fB\$1\\\\fP"],

[$type_enum, "\\\\fI\$1\\\\fP"],

[$type_struct, "\\\\fI\$1\\\\fP"],

[$type_typedef, "\\\\fI\$1\\\\fP"],

[$type_union, "\\\\fI\$1\\\\fP"],

[$type_param, "\\\\fI\$1\\\\fP"],

[$type_param_ref, "\\\\fI\$1\$2\\\\fP"],

[$type_member, "\\\\fI\$1\$2\$3\\\\fP"],

[$type_fallback, "\\\\fI\$1\\\\fP"]

);

my $blankline_man = "";

# rst-mode

my @highlights_rst = (

[$type_constant, "``\$1``"],

[$type_constant2, "``\$1``"],

# Note: need to escape () to avoid func matching later

[$type_member_func, "\\:c\\:type\\:`\$1\$2\$3\\\$\\\$ <\$1>`"],

[$type_member, "\\:c\\:type\\:`\$1\$2\$3 <\$1>`"],

[$type_fp_param, "**\$1\\\$\\\$**"],

[$type_fp_param2, "**\$1\\\$\\\$**"],

[$type_func, "\$1()"],

[$type_enum, "\\:c\\:type\\:`\$1 <\$2>`"],

[$type_struct, "\\:c\\:type\\:`\$1 <\$2>`"],

[$type_typedef, "\\:c\\:type\\:`\$1 <\$2>`"],

[$type_union, "\\:c\\:type\\:`\$1 <\$2>`"],

# in rst this can refer to any type

[$type_fallback, "\\:c\\:type\\:`\$1`"],

[$type_param_ref, "**\$1\$2**"]

);

my $blankline_rst = "\n";

# read arguments

if ($#ARGV == -1) {

usage();

}

my $kernelversion;

my ($sphinx_major, $sphinx_minor, $sphinx_patch);

my $dohighlight = "";

my $verbose = 0;

my $Werror = 0;

my $output_mode = "rst";

my $output_preformatted = 0;

my $no_doc_sections = 0;

my $enable_lineno = 0;

my @highlights = @highlights_rst;

my $blankline = $blankline_rst;

my $modulename = "Kernel API";

use constant {

OUTPUT_ALL => 0, # output all symbols and doc sections

OUTPUT_INCLUDE => 1, # output only specified symbols

OUTPUT_EXPORTED => 2, # output exported symbols

OUTPUT_INTERNAL => 3, # output non-exported symbols

};

my $output_selection = OUTPUT_ALL;

my $show_not_found = 0; # No longer used

my @export_file_list;

my @build_time;

if (defined($ENV{'KBUILD_BUILD_TIMESTAMP'}) &&

(my $seconds = `date -d"${ENV{'KBUILD_BUILD_TIMESTAMP'}}" +%s`) ne '') {

@build_time = gmtime($seconds);

} else {

@build_time = localtime;

}

my $man_date = ('January', 'February', 'March', 'April', 'May', 'June',

'July', 'August', 'September', 'October',

'November', 'December')[$build_time[4]] .

" " . ($build_time[5]+1900);

# Essentially these are globals.

# They probably want to be tidied up, made more localised or something.

# CAVEAT EMPTOR! Some of the others I localised may not want to be, which

# could cause "use of undefined value" or other bugs.

my ($function, %function_table, %parametertypes, $declaration_purpose);

my %nosymbol_table = ();

my $declaration_start_line;

my ($type, $declaration_name, $return_type);

my ($newsection, $newcontents, $prototype, $brcount, %source_map);

if (defined($ENV{'KBUILD_VERBOSE'})) {

$verbose = "$ENV{'KBUILD_VERBOSE'}";

}

if (defined($ENV{'KDOC_WERROR'})) {

$Werror = "$ENV{'KDOC_WERROR'}";

}

if (defined($ENV{'KCFLAGS'})) {

my $kcflags = "$ENV{'KCFLAGS'}";

if ($kcflags =~ /Werror/) {

$Werror = 1;

}

# Generated docbook code is inserted in a template at a point where

# docbook v3.1 requires a non-zero sequence of RefEntry's; see:

# https://www.oasis-open.org/docbook/documentation/reference/html/refentry.html

# We keep track of number of generated entries and generate a dummy

# if needs be to ensure the expanded template can be postprocessed

# into html.

my $section_counter = 0;

my $lineprefix="";

# Parser states

use constant {

STATE_NORMAL => 0, # normal code

STATE_NAME => 1, # looking for function name

STATE_BODY_MAYBE => 2, # body - or maybe more description

STATE_BODY => 3, # the body of the comment

STATE_BODY_WITH_BLANK_LINE => 4, # the body, which has a blank line

STATE_PROTO => 5, # scanning prototype

STATE_DOCBLOCK => 6, # documentation block

STATE_INLINE => 7, # gathering doc outside main block

};

my $state;

my $in_doc_sect;

my $leading_space;

# Inline documentation state

use constant {

STATE_INLINE_NA => 0, # not applicable ($state != STATE_INLINE)

STATE_INLINE_NAME => 1, # looking for member name (@foo:)

STATE_INLINE_TEXT => 2, # looking for member documentation

STATE_INLINE_END => 3, # done

STATE_INLINE_ERROR => 4, # error - Comment without header was found.

# Spit a warning as it's not

# proper kernel-doc and ignore the rest.

};

my $inline_doc_state;

#declaration types: can be

# 'function', 'struct', 'union', 'enum', 'typedef'

my $decl_type;

# Name of the kernel-doc identifier for non-DOC markups

my $identifier;

my $doc_start = '^/\*\*\s*$'; # Allow whitespace at end of comment start.

my $doc_end = '\*/';

my $doc_com = '\s*\*\s*';

my $doc_com_body = '\s*\* ?';

my $doc_decl = $doc_com . '(\w+)';

# @params and a strictly limited set of supported section names

# Specifically:

# Match @word:

# @...:

# @{section-name}:

# while trying to not match literal block starts like "example::"

my $doc_sect = $doc_com .

my $doc_content = $doc_com_body . '(.*)';

my $doc_block = $doc_com . 'DOC:\s*(.*)?';

my $doc_inline_start = '^\s*/\*\*\s*$';

my $doc_inline_sect = '\s*\*\s*(@\s*[\w][\w\.]*\s*):(.*)';

my $doc_inline_end = '^\s*\*/\s*$';

my $doc_inline_oneline = '^\s*/\*\*\s*(@[\w\s]+):\s*(.*)\s*\*/\s*$';

my $export_symbol = '^\s*EXPORT_SYMBOL(_GPL)?\s*$\s*(\w+)\s*$\s*;';

my %parameterdescs;

my %parameterdesc_start_lines;

my @parameterlist;

my %sections;

my @sectionlist;

my %section_start_lines;

my $sectcheck;

my $struct_actual;

my $contents = "";

my $new_start_line = 0;

# the canonical section names. see also $doc_sect above.

my $section_default = "Description"; # default section

my $section_intro = "Introduction";

my $section = $section_default;

my $section_context = "Context";

my $section_return = "Return";

my $undescribed = "-- undescribed --";

reset_state();

while ($ARGV[0] =~ m/^--?(.*)/) {

my $cmd = $1;

shift @ARGV;

if ($cmd eq "man") {

$output_mode = "man";

@highlights = @highlights_man;

$blankline = $blankline_man;

} elsif ($cmd eq "rst") {

$output_mode = "rst";

@highlights = @highlights_rst;

$blankline = $blankline_rst;

} elsif ($cmd eq "none") {

$output_mode = "none";

} elsif ($cmd eq "module") { # not needed for XML, inherits from calling document

$modulename = shift @ARGV;

} elsif ($cmd eq "function") { # to only output specific functions

$output_selection = OUTPUT_INCLUDE;

$function = shift @ARGV;

$function_table{$function} = 1;

} elsif ($cmd eq "nosymbol") { # Exclude specific symbols

my $symbol = shift @ARGV;

$nosymbol_table{$symbol} = 1;

} elsif ($cmd eq "export") { # only exported symbols

$output_selection = OUTPUT_EXPORTED;

%function_table = ();

} elsif ($cmd eq "internal") { # only non-exported symbols

$output_selection = OUTPUT_INTERNAL;

%function_table = ();

} elsif ($cmd eq "export-file") {

my $file = shift @ARGV;

push(@export_file_list, $file);

} elsif ($cmd eq "v") {

$verbose = 1;

} elsif ($cmd eq "Werror") {

$Werror = 1;

} elsif (($cmd eq "h") || ($cmd eq "help")) {

usage();

} elsif ($cmd eq 'no-doc-sections') {

$no_doc_sections = 1;

} elsif ($cmd eq 'enable-lineno') {

$enable_lineno = 1;

} elsif ($cmd eq 'show-not-found') {

$show_not_found = 1; # A no-op but don't fail

} elsif ($cmd eq "sphinx-version") {

my $ver_string = shift @ARGV;

if ($ver_string =~ m/^(\d+)(\.\d+)?(\.\d+)?/) {

$sphinx_major = $1;

if (defined($2)) {

$sphinx_minor = substr($2,1);

} else {

$sphinx_minor = 0;

}

if (defined($3)) {

$sphinx_patch = substr($3,1)

} else {

$sphinx_patch = 0;

}

} else {

die "Sphinx version should either major.minor or major.minor.patch format\n";

}

} else {

# Unknown argument

usage();

}

# continue execution near EOF;

# The C domain dialect changed on Sphinx 3. So, we need to check the

# version in order to produce the right tags.

sub findprog($)

{

foreach(split(/:/, $ENV{PATH})) {

return "$_/$_[0]" if(-x "$_/$_[0]");

}

sub get_sphinx_version()

{

my $ver;

my $cmd = "sphinx-build";

if (!findprog($cmd)) {

my $cmd = "sphinx-build3";

if (!findprog($cmd)) {

$sphinx_major = 1;

$sphinx_minor = 2;

$sphinx_patch = 0;

printf STDERR "Warning: Sphinx version not found. Using default (Sphinx version %d.%d.%d)\n",

$sphinx_major, $sphinx_minor, $sphinx_patch;

return;

}

open IN, "$cmd --version 2>&1 |";

while (<IN>) {

if (m/^\s*sphinx-build\s+([\d]+)\.([\d\.]+)(\+\/[\da-f]+)?$/) {

$sphinx_major = $1;

$sphinx_minor = $2;

$sphinx_patch = $3;

last;

}

# Sphinx 1.2.x uses a different format

if (m/^\s*Sphinx.*\s+([\d]+)\.([\d\.]+)$/) {

$sphinx_major = $1;

$sphinx_minor = $2;

$sphinx_patch = $3;

last;

}

close IN;

}

# get kernel version from env

sub get_kernel_version() {

my $version = 'unknown kernel version';

if (defined($ENV{'KERNELVERSION'})) {

$version = $ENV{'KERNELVERSION'};

}

return $version;

}

sub print_lineno {

my $lineno = shift;

if ($enable_lineno && defined($lineno)) {

print "#define LINENO " . $lineno . "\n";

}

# dumps section contents to arrays/hashes intended for that purpose.

sub dump_section {

my $file = shift;

my $name = shift;

my $contents = join "\n", @_;

if ($name =~ m/$type_param/) {

$name = $1;

$parameterdescs{$name} = $contents;

$sectcheck = $sectcheck . $name . " ";

$parameterdesc_start_lines{$name} = $new_start_line;

$new_start_line = 0;

} elsif ($name eq "@\.\.\.") {

$name = "...";

$parameterdescs{$name} = $contents;

$sectcheck = $sectcheck . $name . " ";

$parameterdesc_start_lines{$name} = $new_start_line;

$new_start_line = 0;

} else {

if (defined($sections{$name}) && ($sections{$name} ne "")) {

# Only warn on user specified duplicate section names.

if ($name ne $section_default) {

print STDERR "${file}:$.: warning: duplicate section name '$name'\n";

++$warnings;

}

$sections{$name} .= $contents;

} else {

$sections{$name} = $contents;

push @sectionlist, $name;

$section_start_lines{$name} = $new_start_line;

$new_start_line = 0;

}

# dump DOC: section after checking that it should go out

sub dump_doc_section {

my $file = shift;

my $name = shift;

my $contents = join "\n", @_;

if ($no_doc_sections) {

return;

}

return if (defined($nosymbol_table{$name}));

if (($output_selection == OUTPUT_ALL) ||

(($output_selection == OUTPUT_INCLUDE) &&

defined($function_table{$name})))

{

dump_section($file, $name, $contents);

output_blockhead({'sectionlist' => \@sectionlist,

'sections' => \%sections,

'module' => $modulename,

'content-only' => ($output_selection != OUTPUT_ALL), });

}

# output function

# parameterdescs, a hash.

# function => "function name"

# parameterlist => @list of parameters

# parameterdescs => %parameter descriptions

# sectionlist => @list of sections

# sections => %section descriptions

sub output_highlight {

my $contents = join "\n",@_;

my $line;

# DEBUG

# if (!defined $contents) {

# use Carp;

# confess "output_highlight got called with no args?\n";

# }

# print STDERR "contents b4:$contents\n";

eval $dohighlight;

die $@ if $@;

# print STDERR "contents af:$contents\n";

foreach $line (split "\n", $contents) {

if (! $output_preformatted) {

$line =~ s/^\s*//;

}

if ($line eq ""){

if (! $output_preformatted) {

print $lineprefix, $blankline;

}

} else {

if ($output_mode eq "man" && substr($line, 0, 1) eq ".") {

print "\\&$line";

} else {

print $lineprefix, $line;

}

print "\n";

}

# output function in man

sub output_function_man(%) {

my %args = %{$_[0]};

my ($parameter, $section);

my $count;

print ".TH \"$args{'function'}\" 9 \"$args{'function'}\" \"$man_date\" \"Kernel Hacker's Manual\" LINUX\n";

print ".SH NAME\n";

print $args{'function'} . " \\- " . $args{'purpose'} . "\n";

print ".SH SYNOPSIS\n";

if ($args{'functiontype'} ne "") {

print ".B \"" . $args{'functiontype'} . "\" " . $args{'function'} . "\n";

} else {

print ".B \"" . $args{'function'} . "\n";

}

$count = 0;

my $parenth = "(";

my $post = ",";

foreach my $parameter (@{$args{'parameterlist'}}) {

if ($count == $#{$args{'parameterlist'}}) {

$post = ");";

}

$type = $args{'parametertypes'}{$parameter};

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

# pointer-to-function

print ".BI \"" . $parenth . $1 . "\" " . " \") (" . $2 . ")" . $post . "\"\n";

} else {

$type =~ s/([^\*])$/$1 /;

print ".BI \"" . $parenth . $type . "\" " . " \"" . $post . "\"\n";

}

$count++;

$parenth = "";

}

print ".SH ARGUMENTS\n";

foreach $parameter (@{$args{'parameterlist'}}) {

my $parameter_name = $parameter;

$parameter_name =~ s/\[.*//;

print ".IP \"" . $parameter . "\" 12\n";

output_highlight($args{'parameterdescs'}{$parameter_name});

}

foreach $section (@{$args{'sectionlist'}}) {

print ".SH \"", uc $section, "\"\n";

output_highlight($args{'sections'}{$section});

}

# output enum in man

sub output_enum_man(%) {

my %args = %{$_[0]};

my ($parameter, $section);

my $count;

print ".TH \"$args{'module'}\" 9 \"enum $args{'enum'}\" \"$man_date\" \"API Manual\" LINUX\n";

print ".SH NAME\n";

print "enum " . $args{'enum'} . " \\- " . $args{'purpose'} . "\n";

print ".SH SYNOPSIS\n";

print "enum " . $args{'enum'} . " {\n";

$count = 0;

foreach my $parameter (@{$args{'parameterlist'}}) {

print ".br\n.BI \" $parameter\"\n";

if ($count == $#{$args{'parameterlist'}}) {

print "\n};\n";

last;

}

else {

print ", \n.br\n";

}

$count++;

}

print ".SH Constants\n";

foreach $parameter (@{$args{'parameterlist'}}) {

my $parameter_name = $parameter;

$parameter_name =~ s/\[.*//;

print ".IP \"" . $parameter . "\" 12\n";

output_highlight($args{'parameterdescs'}{$parameter_name});

}

foreach $section (@{$args{'sectionlist'}}) {

print ".SH \"$section\"\n";

output_highlight($args{'sections'}{$section});

}

# output struct in man

sub output_struct_man(%) {

my %args = %{$_[0]};

my ($parameter, $section);

print ".TH \"$args{'module'}\" 9 \"" . $args{'type'} . " " . $args{'struct'} . "\" \"$man_date\" \"API Manual\" LINUX\n";

print ".SH NAME\n";

print $args{'type'} . " " . $args{'struct'} . " \\- " . $args{'purpose'} . "\n";

my $declaration = $args{'definition'};

$declaration =~ s/\t/ /g;

$declaration =~ s/\n/"\n.br\n.BI \"/g;

print ".SH SYNOPSIS\n";

print $args{'type'} . " " . $args{'struct'} . " {\n.br\n";

print ".BI \"$declaration\n};\n.br\n\n";

print ".SH Members\n";

foreach $parameter (@{$args{'parameterlist'}}) {

($parameter =~ /^#/) && next;

my $parameter_name = $parameter;

$parameter_name =~ s/\[.*//;

($args{'parameterdescs'}{$parameter_name} ne $undescribed) || next;

print ".IP \"" . $parameter . "\" 12\n";

output_highlight($args{'parameterdescs'}{$parameter_name});

}

foreach $section (@{$args{'sectionlist'}}) {

print ".SH \"$section\"\n";

output_highlight($args{'sections'}{$section});

}

# output typedef in man

sub output_typedef_man(%) {

my %args = %{$_[0]};

my ($parameter, $section);

print ".TH \"$args{'module'}\" 9 \"$args{'typedef'}\" \"$man_date\" \"API Manual\" LINUX\n";

print ".SH NAME\n";

print "typedef " . $args{'typedef'} . " \\- " . $args{'purpose'} . "\n";

foreach $section (@{$args{'sectionlist'}}) {

print ".SH \"$section\"\n";

output_highlight($args{'sections'}{$section});

}

sub output_blockhead_man(%) {

my %args = %{$_[0]};

my ($parameter, $section);

my $count;

print ".TH \"$args{'module'}\" 9 \"$args{'module'}\" \"$man_date\" \"API Manual\" LINUX\n";

foreach $section (@{$args{'sectionlist'}}) {

print ".SH \"$section\"\n";

output_highlight($args{'sections'}{$section});

}

# output in restructured text

# This could use some work; it's used to output the DOC: sections, and

# starts by putting out the name of the doc section itself, but that tends

# to duplicate a header already in the template file.

sub output_blockhead_rst(%) {

my %args = %{$_[0]};

my ($parameter, $section);

foreach $section (@{$args{'sectionlist'}}) {

next if (defined($nosymbol_table{$section}));

if ($output_selection != OUTPUT_INCLUDE) {

print ".. _$section:\n\n";

print "**$section**\n\n";

}

print_lineno($section_start_lines{$section});

output_highlight_rst($args{'sections'}{$section});

print "\n";

}

# Apply the RST highlights to a sub-block of text.

sub highlight_block($) {

# The dohighlight kludge requires the text be called $contents

my $contents = shift;

eval $dohighlight;

die $@ if $@;

return $contents;

}

# Regexes used only here.

my $sphinx_literal = '^[^.].*::$';

my $sphinx_cblock = '^\.\.\ +code-block::';

sub output_highlight_rst {

my $input = join "\n",@_;

my $output = "";

my $line;

my $in_literal = 0;

my $litprefix;

my $block = "";

foreach $line (split "\n",$input) {

# If we're in a literal block, see if we should drop out

# of it. Otherwise pass the line straight through unmunged.

if ($in_literal) {

if (! ($line =~ /^\s*$/)) {

# If this is the first non-blank line in a literal

# block we need to figure out what the proper indent is.

if ($litprefix eq "") {

$line =~ /^(\s*)/;

$litprefix = '^' . $1;

$output .= $line . "\n";

} elsif (! ($line =~ /$litprefix/)) {

$in_literal = 0;

} else {

$output .= $line . "\n";

}

} else {

$output .= $line . "\n";

}

# Not in a literal block (or just dropped out)

if (! $in_literal) {

$block .= $line . "\n";

if (($line =~ /$sphinx_literal/) || ($line =~ /$sphinx_cblock/)) {

$in_literal = 1;

$litprefix = "";

$output .= highlight_block($block);

$block = ""

}

if ($block) {

$output .= highlight_block($block);

}

foreach $line (split "\n", $output) {

print $lineprefix . $line . "\n";

}

sub output_function_rst(%) {

my %args = %{$_[0]};

my ($parameter, $section);

my $oldprefix = $lineprefix;

my $start = "";

my $is_macro = 0;

if ($sphinx_major < 3) {

if ($args{'typedef'}) {

print ".. c:type:: ". $args{'function'} . "\n\n";

print_lineno($declaration_start_line);

print " **Typedef**: ";

$lineprefix = "";

output_highlight_rst($args{'purpose'});

$start = "\n\n**Syntax**\n\n ``";

$is_macro = 1;

} else {

print ".. c:function:: ";

}

} else {

if ($args{'typedef'} || $args{'functiontype'} eq "") {

$is_macro = 1;

print ".. c:macro:: ". $args{'function'} . "\n\n";

} else {

print ".. c:function:: ";

}

if ($args{'typedef'}) {

print_lineno($declaration_start_line);

print " **Typedef**: ";

$lineprefix = "";

output_highlight_rst($args{'purpose'});

$start = "\n\n**Syntax**\n\n ``";

} else {

print "``" if ($is_macro);

}

if ($args{'functiontype'} ne "") {

$start .= $args{'functiontype'} . " " . $args{'function'} . " (";

} else {

$start .= $args{'function'} . " (";

}

print $start;

my $count = 0;

foreach my $parameter (@{$args{'parameterlist'}}) {

if ($count ne 0) {

print ", ";

}

$count++;

$type = $args{'parametertypes'}{$parameter};

if ($type =~ m/([^$]*\(\*)\s*$\s*$([^$]*)\)/) {

# pointer-to-function

print $1 . $parameter . ") (" . $2 . ")";

} else {

print $type;

}

if ($is_macro) {

print ")``\n\n";

} else {

print ")\n\n";

}

if (!$args{'typedef'}) {

print_lineno($declaration_start_line);

$lineprefix = " ";

output_highlight_rst($args{'purpose'});

print "\n";

}

print "**Parameters**\n\n";

$lineprefix = " ";

foreach $parameter (@{$args{'parameterlist'}}) {

my $parameter_name = $parameter;

$parameter_name =~ s/\[.*//;

View remainder of file in raw view

linux/scripts/kernel-doc at master · linuxkit/linux · GitHub

Uh oh!

Expand file tree

Breadcrumbs

kernel-doc

Latest commit

History

Breadcrumbs

kernel-doc

File metadata and controls