From d96de58adf41d4c0d0fc449cb68d55d8658097b2 Mon Sep 17 00:00:00 2001 From: Karl Williamson Date: Mon, 28 Jul 2025 18:12:20 -0600 Subject: [PATCH] perlapi: PL_check and PL_hexdigit are arrays not macros This fact is important to Devel::PPPort. It means autodoc has to now recognize the @ flag. And embed.fnc is updated to document this flag --- autodoc.pl | 3 ++- embed.fnc | 52 ++++++++++++++++++++++++++++------------------------ perl.h | 2 +- perlvars.h | 2 +- 4 files changed, 32 insertions(+), 27 deletions(-) diff --git a/autodoc.pl b/autodoc.pl index 73eed7413b..a8d2a43981 100644 --- a/autodoc.pl +++ b/autodoc.pl @@ -74,7 +74,7 @@ use strict; use warnings; my $known_flags_re = - qr/[aA bC dD eE fF Gh iI mM nN oO pP rR sS T uU vW xX y;#?]/xx; + qr/[ aA bC dD eE fF Gh iI mM nN oO pP rR sS T uU vW xX y ;@#? ] /xx; # Flags that don't apply to this program, like implementation details. my $irrelevant_flags_re = qr/[ab eE G iI P rR vX?]/xx; @@ -537,6 +537,7 @@ sub check_and_add_proto_defn { } $flags .= "m" if $flags =~ /M/; + $flags .= "U" if $flags =~ /@/; # No usage output for @arrays my @munged_args= $args_ref->@*; s/\b(?:NN|NULLOK)\b\s+//g for @munged_args; diff --git a/embed.fnc b/embed.fnc index dec2190e1e..888bc28049 100644 --- a/embed.fnc +++ b/embed.fnc @@ -5,14 +5,14 @@ : This file is known to be processed by regen/embed.pl, autodoc.pl, : makedef.pl, Devel::PPPort, and porting/diag.t. : -: This file contains entries for various functions and macros defined by perl. -: Each entry includes the name, parameters, and various attributes about it. -: In most functions listed here, the name is a short name, and the function's -: real name is the short one, prefixed by either 'Perl_' (for publicly visible -: functions) or 'S_' (for internal-to-a-file static ones). In many instances a -: macro is defined that is the name in this file, and which expands to call the -: real (full) name, with any appropriate thread context paramaters, thus hiding -: that detail from the typical code. +: This file contains entries for various functions, macros, typedefs, and +: arrays defined by perl. Each entry includes the name, parameters, and +: various attributes about it. In most functions listed here, the name is a +: short name, and the function's real name is the short one, prefixed by either +: 'Perl_' (for publicly visible functions) or 'S_' (for internal-to-a-file +: static ones). In many instances a macro is defined that is the name in this +: file, and which expands to call the real (full) name, with any appropriate +: thread context paramaters, thus hiding that detail from the typical code. : : Many macros (as opposed to functions) listed here are the complete full name, : though we may want to start converting those to have full names. @@ -140,27 +140,27 @@ : =for apidoc_item name ... : =for apidoc_defn name ... : -: The purpose of these lines is to furnish documentation for functions and -: macros. The lines tend to be placed near the source for the item they +: The purpose of these lines is to furnish documentation for functions, +: macros, etc. The lines tend to be placed near the source for the item they : describe. autodoc.pl is run as part of the standard build process to : extract this documentation and build either perlapi.pod (from the elements : that are flagged as A in this file), or perlintern.pod (from the other : elements. : -: Functions need to be specified in this file, but macros may not necessarily -: be. The information in this file is sufficient to generate a usage line for -: the element to be documented; otherwise that information needs to be -: specified in the apidoc-ish lines. +: Functions need to be specified in this file, but macros and other types of +: elements may not necessarily be. The information in this file is sufficient +: to generate a usage line for the element to be documented; otherwise that +: information needs to be specified in the apidoc-ish lines. : -: 'apidoc_defn' was added to supplement, for macros, the information in this -: file. It is designed to be placed at the point of definition of the macro -: it is for, so that the information can easily be checked for correctness, -: and you know at a glance that the macro actually has documentation. It -: doesn't by itself create any documentation; instead the other apidoc lines -: pull in information specified by these lines. Many of the lines in this -: file for macros that don't also have the 'p' flag (described below) could be -: pulled out of here and replaced by these lines throughout the source. It is -: a goal to do that as convenience dictates. +: 'apidoc_defn' was added to supplement, for non-functions, the information in +: this file. It is designed to be placed at the point of definition of the +: element it is for, so that the information can easily be checked for +: correctness, and you know at a glance that the element actually has +: documentation. It doesn't by itself create any documentation; instead the +: other apidoc lines pull in information specified by these lines. Many of the +: lines in this file for macros that don't also have the 'p' flag (described +: below) could be pulled out of here and replaced by these lines throughout the +: source. It is a goal to do that as convenience dictates. : : The other apidoc lines either have the usage data as part of the line, or : pull in the data from this file or apidoc_defn lines. @@ -223,7 +223,7 @@ : : The 'name' in any such line must not be the same as any in this file (i.e., : no redundant definitions), and one of the flags on the apidoc lines must be -: 'm' or 'y', indicating it is not a function. +: 'm', 'y', or '@', indicating it is not a function. : : All but the name field of an apidoc_item line are optional, and if empty, : inherits from a corresponding apidoc_defn line, if one exists, or the @@ -612,6 +612,10 @@ : : 'y' Typedef. The element names a type rather than being a macro : +: '@' This entry is for an array, as opposed to a function or macro, etc. +: +: autodoc.pl automatically suppresses any usage information. +: : ';' autodoc.pl adds a terminating semi-colon to the usage example in the : documentation. : diff --git a/perl.h b/perl.h index 49acc8be06..1154cb99df 100644 --- a/perl.h +++ b/perl.h @@ -5419,7 +5419,7 @@ EXTCONST char PL_Zero[] /* =for apidoc_section $numeric -=for apidoc AmTuU|const char *|PL_hexdigit|U8 value +=for apidoc A@T|const char *|PL_hexdigit|U8 value This array, indexed by an integer, converts that value into the character that represents it. For example, if the input is 8, the return will be a string diff --git a/perlvars.h b/perlvars.h index 8d71b11760..7b0c01a43f 100644 --- a/perlvars.h +++ b/perlvars.h @@ -123,7 +123,7 @@ PERLVARI(G, C_locale_obj, locale_t, NULL) PERLVARI(G, watch_pvx, char *, NULL) /* -=for apidoc AmnU|Perl_check_t *|PL_check +=for apidoc A@nU|Perl_check_t *|PL_check Array, indexed by opcode, of functions that will be called for the "check" phase of optree building during compilation of Perl code. For most (but