Mercurial > octave

annotate libinterp/mk-doc.pl @ 33608:5fba13104493 bytecode-interpreter tip

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
maint: merge default to bytecode-interpreter.
author Nicholas R. Jankowski <jankowski.nicholas@gmail.com>
date Sat, 18 May 2024 22:40:00 -0400
parents 2e484f9f1f18
children
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
1 #! /usr/bin/perl -w
29357
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
2
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
3 ########################################################################
29357
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
4 ##
32632
2e484f9f1f18 maint: update Octave Project Developers copyright for the new year
John W. Eaton <jwe@octave.org>
parents: 31706
diff changeset
5 ## Copyright (C) 2012-2024 The Octave Project Developers
29357
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
6 ##
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
7 ## See the file COPYRIGHT.md in the top-level directory of this
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
8 ## distribution or <https://octave.org/copyright/>.
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
9 ##
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
10 ## This file is part of Octave.
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
11 ##
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
12 ## Octave is free software: you can redistribute it and/or modify it
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
13 ## under the terms of the GNU General Public License as published by
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
14 ## the Free Software Foundation, either version 3 of the License, or
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
15 ## (at your option) any later version.
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
16 ##
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
17 ## Octave is distributed in the hope that it will be useful, but
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
18 ## WITHOUT ANY WARRANTY; without even the implied warranty of
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
19 ## MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
20 ## GNU General Public License for more details.
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
21 ##
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
22 ## You should have received a copy of the GNU General Public License
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
23 ## along with Octave; see the file COPYING. If not, see
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
24 ## <https://www.gnu.org/licenses/>.
bbbe4dcc7200 use the same comment style for copyright headers in .m files and shell scripts
John W. Eaton <jwe@octave.org>
parents: 27923
diff changeset
25 ##
27923
bd51beb6205e update formatting of copyright notices
John W. Eaton <jwe@octave.org>
parents: 27919
diff changeset
26 ########################################################################
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
27
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
28 unless (@ARGV > 1) { die "Usage: $0 SRCDIR src-file1 ..." }
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
29
21967
17457503ba95 gendoc.pl: Minor changes for readability and speed.
Rik <rik@octave.org>
parents: 21966
diff changeset
30 $srcdir = shift (@ARGV);
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
31
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
32 print <<__END_OF_MSG__;
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
33 ### DO NOT EDIT!
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
34 ###
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
35 ### This file is generated automatically from Octave source files.
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
36 ### Edit source files directly and run make to update this file.
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
37
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
38 __END_OF_MSG__
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
39
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
40 FILE: foreach $fname (@ARGV)
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
41 {
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
42 if (-f "$fname")
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
43 {
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
44 $src_fname = "$fname";
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
45 }
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
46 else
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
47 {
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
48 $src_fname = "$srcdir/$fname";
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
49 }
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
50
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
51 open (SRC_FH, $src_fname) or die "Unable to open $src_fname";
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
52
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
53 @func_list = ();
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
54 @docstr = ();
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
55
22893
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
56 LINE: while (my $line = <SRC_FH>)
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
57 {
29968
7aa4d8c049e5 eliminate obsolete DEFCONSTFUN and DEFCONSTMETHOD macros
John W. Eaton <jwe@octave.org>
parents: 29967
diff changeset
58 if ($line =~ /^\s*DEF(?:METHOD|METHOD_(|STATIC_)DLD|METHODX|METHODX_(|STATIC_)DLD|UN|UN_(|STATIC_)DLD|UNX|UNX_(|STATIC_)DLD)\s*\(/)
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
59 {
22893
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
60 ($func) = $line =~ /\("?(\w+)"?,/;
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
61 unless ($func) { die "Unable to parse $src_fname at line $.\n" }
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
62 push (@func_list, $func);
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
63
22893
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
64 ## Skip optional line that declares list of classes that this
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
65 ## function accepts.
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
66 $line = <SRC_FH>;
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
67 if ($line =~ m#\s*classes:#)
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
68 {
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
69 $line = <SRC_FH>;
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
70 }
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
71
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
72 if ($line =~ m#\s*doc:\s+\Q/*\E\s+\Q-*- texinfo -*-\E\s*$#)
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
73 {
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
74 $str = "-*- texinfo -*-\n";
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
75 $reading_docstring = 1;
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
76 }
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
77 else
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
78 {
23709
3b68aeeabc40 rename some build scripts for consistency and move them to where they are used
John W. Eaton <jwe@octave.org>
parents: 23518
diff changeset
79 print STDERR "mk-doc.pl: undocumented function $func from $fname\n";
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
80 push (@docstr, "Undocumented.");
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
81 }
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
82 }
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
83 elsif ($reading_docstring)
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
84 {
22893
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
85 if ($line =~ /^.*\s+\*\/\s*\)\s*$/)
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
86 {
22893
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
87 $line =~ s#\s+\*/\s*\)\s*$##;
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
88 push (@docstr, $str . $line);
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
89 $reading_docstring = 0;
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
90 }
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
91 else
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
92 {
22893
5ff6716cf157 allow dispatch types to be declared for built-in functions
John W. Eaton <jwe@octave.org>
parents: 22755
diff changeset
93 $str .= $line;
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
94 }
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
95 }
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
96 }
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
97 close (SRC_FH);
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
98
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
99 ## Print results in DOCSTRING format
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
100 foreach $i (0 .. $#func_list)
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
101 {
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
102 $func = $func_list[$i];
17256
ee1d19174316 doc: Use 0x1d as record separator for joint compatibility with Texinfo 4.x and 5.x.
Rik <rik@octave.org>
parents: 17242
diff changeset
103 print "\x{1d}$func\n";
21966
112b20240c87 move docstrings in C++ files out of C strings and into comments
John W. Eaton <jwe@octave.org>
parents: 19697
diff changeset
104 print "\@c $func $fname\n";
14649
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
105 print $docstr[$i],"\n";
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
106 }
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
107
5fa6a41d4fbe build: Use Perl to create DOCSTRINGS in src/ directory.
Rik <octave@nomad.inbox5.com>
parents:
diff changeset
108 }