Document cPERLscope

[perl5.git] / perl.h

diff --git a/perl.h b/perl.h
index ec94327..dab7546 100644 (file)
--- a/perl.h
+++ b/perl.h
@@ -84,6 +84,7 @@
 /* <--- here ends the logic shared by perl.h and makedef.pl */
 
 /*
+=for apidoc_section Compiler directives
 =for apidoc AmnUu|void|EXTERN_C
 When not compiling using C++, expands to nothing.
 Otherwise is used in a declaration of a function to indicate the function
@@ -179,6 +180,14 @@ Otherwise ends a section of code already begun by a C<L</START_EXTERN_C>>.
  * implementation of multiplicity using C++ objects. They have been left
  * here solely for the sake of XS code which has incorrectly
  * cargo-culted them.
+ *
+ * The only one Devel::PPPort handles is this; list it as deprecated
+
+=for apidoc_section Concurrency
+=for apidoc AmD|void|CPERLscope|void x
+Now a no-op.
+
+=cut
  */
 #define CPERLscope(x) x
 #define CPERLarg void
@@ -408,8 +417,6 @@ Otherwise ends a section of code already begun by a C<L</START_EXTERN_C>>.
  * but we cannot quite get rid of, such as "ax" in PPCODE+noargs xsubs,
  * or variables/arguments that are used only in certain configurations.
 
-=head1 Miscellaneous Functions
-
 =for apidoc Am||PERL_UNUSED_ARG|void x
 This is used to suppress compiler warnings that a parameter to a function is
 not used.  This situation can arise, for example, when a parameter is needed
@@ -633,29 +640,41 @@ __typeof__ and nothing else.
 #endif
 
 /*
-=head1 Miscellaneous Functions
-
+=for apidoc_section Compiler directives
 =for apidoc AmnUu|void|STMT_START
+=for apidoc_item ||STMT_END
 
- STMT_START { statements; } STMT_END;
-
-can be used as a single statement, as in
+This allows a series of statements in a macro to be used as a single statement,
+as in
 
- if (x) STMT_START { ... } STMT_END; else ...
+ if (x) STMT_START { ... } STMT_END else ...
 
-These are often used in macro definitions.  Note that you can't return a value
-out of them.
-
-=for apidoc AmnUhu|void|STMT_END
+Note that you can't return a value out of them, which limits their utility.
+But see C<L</PERL_USE_GCC_BRACE_GROUPS>>.
 
 =for apidoc AmnuU|bool|PERL_USE_GCC_BRACE_GROUPS
 
 This C pre-processor value, if defined, indicates that it is permissible to use
-the GCC brace groups extension.  This extension is of the form C<({
-I<STATEMENTS> })>, and turns the block consisting of I<STATEMENTS> into an
-expression with a value, unlike plain C language blocks.  This can present
-optimization possibilities, but there always needs to be an alternative in case
-this ability doesn't exist or has otherwise been forbidden.
+the GCC brace groups extension.  This extension, of the form
+
+ ({ statement ... })
+
+turns the block consisting of I<statements ...> into an expression with a
+value, unlike plain C language blocks.  This can present optimization
+possibilities, B<BUT> you generally need to specify an alternative in case this
+ability doesn't exist or has otherwise been forbidden.
+
+Example usage:
+
+=over
+
+ #ifdef PERL_USE_GCC_BRACE_GROUPS
+   ...
+ #else
+   ...
+ #endif
+
+=back
 
 =cut
 
@@ -1076,6 +1095,7 @@ EXTERN_C int usleep(unsigned int);
 #  endif
 
 /*
+=for apidoc_section Integer configuration values
 =for apidoc Am||INTMAX_C|number
 Returns a token the C compiler recognizes for the constant C<number> of the
 widest integer type on the machine.  For example, if the machine has C<long
@@ -1404,7 +1424,7 @@ EXTERN_C char *crypt(const char *, const char *);
 #endif
 
 /*
-=head1 Errno
+=for apidoc_section Errno
 
 =for apidoc m|void|SETERRNO|int errcode|int vmserrcode
 
@@ -1507,7 +1527,7 @@ was saved by C<dSAVE_ERRNO> or C<RESTORE_ERRNO>.
 #endif
 
 /*
-=head1 Warning and Dieing
+=for apidoc_section Warning and Dieing
 
 =for apidoc Amn|SV *|ERRSV
 
@@ -1585,6 +1605,7 @@ any magic.
 #endif
 
 /*
+=for apidoc_section SV Handling
 =for apidoc Amn|SV *|DEFSV
 Returns the SV associated with C<$_>
 
@@ -1806,8 +1827,7 @@ Localize C<$_>.  See L<perlguts/Localizing changes>.
  * longer need that. XS modules can (and do) use this name, so it must remain
  * a part of the API that's visible to modules.
 
-=head1 Miscellaneous Functions
-
+=for apidoc_section String Handling
 =for apidoc ATmD|int|my_sprintf|NN char *buffer|NN const char *pat|...
 
 Do NOT use this due to the possibility of overflowing C<buffer>.  Instead use
@@ -2631,45 +2651,28 @@ extern long double Perl_my_frexpl(long double x, int *e);
 #endif
 
 /*
-=head1 Numeric functions
-
-=for apidoc AmnUh||PERL_INT_MIN
-=for apidoc AmnUh||PERL_LONG_MAX
-=for apidoc AmnUh||PERL_LONG_MIN
-=for apidoc AmnUh||PERL_QUAD_MAX
-=for apidoc AmnUh||PERL_SHORT_MAX
-=for apidoc AmnUh||PERL_SHORT_MIN
-=for apidoc AmnUh||PERL_UCHAR_MAX
-=for apidoc AmnUh||PERL_UCHAR_MIN
-=for apidoc AmnUh||PERL_UINT_MAX
-=for apidoc AmnUh||PERL_UINT_MIN
-=for apidoc AmnUh||PERL_ULONG_MAX
-=for apidoc AmnUh||PERL_ULONG_MIN
-=for apidoc AmnUh||PERL_UQUAD_MAX
-=for apidoc AmnUh||PERL_UQUAD_MIN
-=for apidoc AmnUh||PERL_USHORT_MAX
-=for apidoc AmnUh||PERL_USHORT_MIN
-=for apidoc AmnUh||PERL_QUAD_MIN
+=for apidoc_section Integer configuration values
+
 =for apidoc AmnU||PERL_INT_MAX
-This and
-C<PERL_INT_MIN>,
-C<PERL_LONG_MAX>,
-C<PERL_LONG_MIN>,
-C<PERL_QUAD_MAX>,
-C<PERL_SHORT_MAX>,
-C<PERL_SHORT_MIN>,
-C<PERL_UCHAR_MAX>,
-C<PERL_UCHAR_MIN>,
-C<PERL_UINT_MAX>,
-C<PERL_UINT_MIN>,
-C<PERL_ULONG_MAX>,
-C<PERL_ULONG_MIN>,
-C<PERL_UQUAD_MAX>,
-C<PERL_UQUAD_MIN>,
-C<PERL_USHORT_MAX>,
-C<PERL_USHORT_MIN>,
-C<PERL_QUAD_MIN>
-give the largest and smallest number representable in the current
+=for apidoc_item ||PERL_INT_MIN
+=for apidoc_item ||PERL_LONG_MAX
+=for apidoc_item ||PERL_LONG_MIN
+=for apidoc_item ||PERL_SHORT_MAX
+=for apidoc_item ||PERL_SHORT_MIN
+=for apidoc_item ||PERL_UCHAR_MAX
+=for apidoc_item ||PERL_UCHAR_MIN
+=for apidoc_item ||PERL_UINT_MAX
+=for apidoc_item ||PERL_UINT_MIN
+=for apidoc_item ||PERL_ULONG_MAX
+=for apidoc_item ||PERL_ULONG_MIN
+=for apidoc_item ||PERL_USHORT_MAX
+=for apidoc_item ||PERL_USHORT_MIN
+=for apidoc_item ||PERL_QUAD_MAX
+=for apidoc_item ||PERL_QUAD_MIN
+=for apidoc_item ||PERL_UQUAD_MAX
+=for apidoc_item ||PERL_UQUAD_MIN
+
+These give the largest and smallest number representable in the current
 platform in variables of the corresponding types.
 
 For signed types, the smallest representable number is the most negative
@@ -3068,7 +3071,7 @@ typedef struct padname PADNAME;
 #endif
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section Embedding and Interpreter Cloning
 
 =for apidoc Am|void|PERL_SYS_INIT|int *argc|char*** argv
 Provides system-specific tune up of the C runtime environment necessary to
@@ -3625,11 +3628,8 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex)
 
 #define HEKfARG(p) ((void*)(p))
 
-/*
-=for apidoc Amnh||UTF8f
-=for apidoc Amh||UTF8fARG|bool is_utf8|Size_t byte_len|char *str
-
-=cut
+/* Documented in perlguts
+ *
  * %4p is a custom format
  */
 #ifndef UTF8f
@@ -3668,14 +3668,14 @@ EXTERN_C int perl_tsa_mutex_unlock(perl_mutex* mutex)
 #endif
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section Compiler directives
 
-=for apidoc AmU|bool|LIKELY|const bool expr
+=for apidoc Am||LIKELY|bool expr
 
 Returns the input unchanged, but at the same time it gives a branch prediction
 hint to the compiler that this condition is likely to be true.
 
-=for apidoc AmU|bool|UNLIKELY|const bool expr
+=for apidoc Am||UNLIKELY|bool expr
 
 Returns the input unchanged, but at the same time it gives a branch prediction
 hint to the compiler that this condition is likely to be false.
@@ -4740,6 +4740,22 @@ EXTCONST char PL_No[]
   INIT("");
 EXTCONST char PL_Zero[]
   INIT("0");
+
+/*
+=for apidoc_section Numeric Functions
+=for apidoc AmTuU|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
+whose first character is '8'.  What is actually returned is a pointer into a
+string.  All you are interested in is the first character of that string.  To
+get uppercase letters (for the values 10..15), add 16 to the index.  Hence,
+C<PL_hexdigit[11]> is C<'b'>, and C<PL_hexdigit[11+16]> is C<'B'>.  Adding 16
+to an index whose representation is '0'..'9' yields the same as not adding 16.
+Indices outside the range 0..31 result in (bad) undedefined behavior.
+
+=cut
+*/
 EXTCONST char PL_hexdigit[]
   INIT("0123456789abcdef0123456789ABCDEF");
 
@@ -6192,7 +6208,7 @@ typedef struct am_table_short AMTS;
                         cBOOL(PL_hints & (HINT_LOCALE|HINT_LOCALE_PARTIAL))
 
 /*
-=head1 Locale-related functions and macros
+=for apidoc_section Locales
 
 =for apidoc Amn|bool|IN_LOCALE
 
@@ -6460,7 +6476,7 @@ the plain locale pragma without a parameter (S<C<use locale>>) is in effect.
  * operations used by Perl, namely the decimal point, and even the thousands
  * separator.)
 
-=head1 Locale-related functions and macros
+=for apidoc_section Locales
 
 =for apidoc Amn|void|DECLARATION_FOR_LC_NUMERIC_MANIPULATION
 
@@ -6753,7 +6769,7 @@ cannot have changed since the precalculation.
 
 /*
 
-=head1 Numeric functions
+=for apidoc_section Numeric Functions
 
 =for apidoc AmTR|NV|Strtod|NN const char * const s|NULLOK char ** e
 
@@ -7081,7 +7097,7 @@ EXTERN_C int flock(int fd, int op);
 #define IS_NUMBER_TRAILING            0x40 /* number has trailing trash */
 
 /*
-=head1 Numeric functions
+=for apidoc_section Numeric Functions
 
 =for apidoc AmdR|bool|GROK_NUMERIC_RADIX|NN const char **sp|NN const char *send
 
@@ -7190,6 +7206,7 @@ extern void moncontrol(int);
 #define PERL_UNICODE_UTF8CACHEASSERT           'a'
 
 /*
+=for apidoc_section Signals
 =for apidoc Amn|U32|PERL_SIGNALS_UNSAFE_FLAG
 If this bit in C<PL_signals> is set, the system is uing the pre-Perl 5.8
 unsafe signals.  See L<perlrun/PERL_SIGNALS> and L<perlipc/Deferred Signals
@@ -7200,7 +7217,7 @@ unsafe signals.  See L<perlrun/PERL_SIGNALS> and L<perlipc/Deferred Signals
 #define PERL_SIGNALS_UNSAFE_FLAG       0x0001
 
 /*
-=head1 Numeric functions
+=for apidoc_section Numeric Functions
 
 =for apidoc Am|int|PERL_ABS|int
 
@@ -7232,7 +7249,7 @@ so no C<x++>.
 
 
 /*
-=head1 Miscellaneous Functions
+=for apidoc_section Utility Functions
 
 =for apidoc Am|bool|IS_SAFE_SYSCALL|NN const char *pv|STRLEN len|NN const char *what|NN const char *op_name