Skip to content

Commit 51b56f5

Browse files
khwilliamsonkhwilliamson
committed
Reorganize perlapi
This uses a new organization of sections that I came up with. I asked for comments on p5p, but there were none.
1 parent 70b05c7 commit 51b56f5

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

44 files changed

+148
-103
lines changed

‎XSUB.h

+1-3
Original file line numberDiff line numberDiff line change
@@ -14,7 +14,7 @@
1414
/* first, some documentation for xsubpp-generated items */
1515

1616
/*
17-
=head1 C<xsubpp> variables and internal functions
17+
=for apidoc_section XS
1818
1919
=for apidoc Amn|char*|CLASS
2020
Variable which is setup by C<xsubpp> to indicate the
@@ -258,8 +258,6 @@ Return C<&PL_sv_undef> from an XSUB immediately. Uses C<XST_mUNDEF>.
258258
=for apidoc Amns||XSRETURN_EMPTY
259259
Return an empty list from an XSUB immediately.
260260
261-
=head1 Variables created by C<xsubpp> and C<xsubpp> internal functions
262-
263261
=for apidoc AmU||newXSproto|char* name|XSUBADDR_t f|char* filename|const char *proto
264262
Used by C<xsubpp> to hook up XSUBs as Perl subs. Adds Perl prototypes to
265263
the subs.

‎av.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -16,7 +16,7 @@
1616
*/
1717

1818
/*
19-
=head1 Array Manipulation Functions
19+
=for apidoc_section AV Handling
2020
*/
2121

2222
#include "EXTERN.h"

‎av.h

-2
Original file line numberDiff line numberDiff line change
@@ -44,8 +44,6 @@ Null AV pointer.
4444
4545
(deprecated - use C<(AV *)NULL> instead)
4646
47-
=head1 Array Manipulation Functions
48-
4947
=for apidoc Am|int|AvFILL|AV* av
5048
Same as C<av_top_index()> or C<av_tindex()>.
5149

‎cop.h

-8
Original file line numberDiff line numberDiff line change
@@ -480,10 +480,6 @@ struct cop {
480480
#define CopHINTHASH_get(c) ((COPHH*)((c)->cop_hints_hash))
481481
#define CopHINTHASH_set(c,h) ((c)->cop_hints_hash = (h))
482482

483-
/*
484-
=head1 COP Hint Reading
485-
*/
486-
487483
/*
488484
=for apidoc Am|SV *|cop_hints_fetch_pvn|const COP *cop|const char *keypv|STRLEN keylen|U32 hash|U32 flags
489485
@@ -941,10 +937,6 @@ struct context {
941937

942938
#define CXINC (cxstack_ix < cxstack_max ? ++cxstack_ix : (cxstack_ix = cxinc()))
943939

944-
/*
945-
=head1 "Gimme" Values
946-
*/
947-
948940
/*
949941
=for apidoc AmnU||G_SCALAR
950942
Used to indicate scalar context. See C<L</GIMME_V>>, C<L</GIMME>>, and

‎cv.h

+4-7
Original file line numberDiff line numberDiff line change
@@ -16,18 +16,16 @@ struct xpvcv {
1616
};
1717

1818
/*
19-
=head1 Handy Values
19+
=head1 CV Handling
20+
21+
This section documents functions to manipulate CVs which are code-values,
22+
meaning subroutines. For more information, see L<perlguts>.
2023
2124
=for apidoc ADmnU||Nullcv
2225
Null CV pointer.
2326
2427
(deprecated - use C<(CV *)NULL> instead)
2528
26-
=head1 CV Manipulation Functions
27-
28-
This section documents functions to manipulate CVs which are code-values,
29-
or subroutines. For more information, see L<perlguts>.
30-
3129
=for apidoc Am|HV*|CvSTASH|CV* cv
3230
Returns the stash of the CV. A stash is the symbol table hash, containing
3331
the package-scoped variables in the package where the subroutine was defined.
@@ -255,7 +253,6 @@ CvNAME_HEK(CV *sv)
255253
)
256254

257255
/*
258-
=head1 CV reference counts and CvOUTSIDE
259256
260257
=for apidoc m|bool|CvWEAKOUTSIDE|CV *cv
261258

‎doio.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -3252,7 +3252,7 @@ Perl_do_shmio(pTHX_ I32 optype, SV **mark, SV **sp)
32523252
#endif /* SYSV IPC */
32533253

32543254
/*
3255-
=head1 IO Functions
3255+
=for apidoc_section Input/Output
32563256
32573257
=for apidoc start_glob
32583258

‎dump.c

-4
Original file line numberDiff line numberDiff line change
@@ -528,10 +528,6 @@ Perl_sv_peek(pTHX_ SV *sv)
528528
return SvPV_nolen(t);
529529
}
530530

531-
/*
532-
=head1 Debugging Utilities
533-
*/
534-
535531
void
536532
Perl_dump_indent(pTHX_ I32 level, PerlIO *file, const char* pat, ...)
537533
{

‎gv.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -20,7 +20,7 @@
2020
*/
2121

2222
/*
23-
=head1 GV Functions
23+
=head1 GV Handling
2424
A GV is a structure which corresponds to to a Perl typeglob, ie *foo.
2525
It is a structure that holds a pointer to a scalar, an array, a hash etc,
2626
corresponding to $foo, @foo, %foo.

‎gv.h

+1-1
Original file line numberDiff line numberDiff line change
@@ -72,7 +72,7 @@ struct gp {
7272
#define GvNAMELEN(gv) GvNAMELEN_get(gv)
7373

7474
/*
75-
=head1 GV Functions
75+
=for apidoc_section GV Handling
7676
7777
=for apidoc Am|SV*|GvSV|GV* gv
7878

‎handy.h

+40-10
Original file line numberDiff line numberDiff line change
@@ -18,15 +18,39 @@
1818
# define Null(type) ((type)NULL)
1919

2020
/*
21-
=head1 Handy Values
22-
21+
=for apidoc_section String Handling
2322
=for apidoc AmnU||Nullch
2423
Null character pointer. (No longer available when C<PERL_CORE> is
2524
defined.)
2625
26+
=for apidoc_section SV Handling
2727
=for apidoc AmnU||Nullsv
2828
Null SV pointer. (No longer available when C<PERL_CORE> is defined.)
2929
30+
=cut
31+
32+
Below are signatures of functions from config.h which can't easily be gleaned
33+
from it, and are very unlikely to change
34+
35+
=for apidoc_section Signals
36+
=for apidoc Am|int|Sigsetjmp|jmp_buf env|int savesigs
37+
=for apidoc Am|void|Siglongjmp|jmp_buf env|int val
38+
39+
=for apidoc_section Filesystem configuration values
40+
=for apidoc Am|void *|FILE_ptr|FILE * f
41+
=for apidoc Am|Size_t|FILE_cnt|FILE * f
42+
=for apidoc Am|void *|FILE_base|FILE * f
43+
=for apidoc Am|Size_t|FILE_bufsiz
44+
45+
=for apidoc_section String Handling
46+
=for apidoc Am|token|CAT2|token x|token y
47+
=for apidoc Am|string|STRINGIFY|token x
48+
49+
=for apidoc_section Numeric Functions
50+
=for apidoc Am|double|Drand01|double x
51+
=for apidoc Am|void|seedDrand01|Rand_seed_t x
52+
=for apidoc Am|char *|Gconvert|double x|Size_t n|bool t|char * b
53+
3054
=cut
3155
*/
3256

@@ -98,6 +122,7 @@ Null SV pointer. (No longer available when C<PERL_CORE> is defined.)
98122
#endif
99123

100124
/*
125+
=for apidoc_section Casting
101126
=for apidoc Am|bool|cBOOL|bool expr
102127
103128
Cast-to-bool. A simple S<C<(bool) I<expr>>> cast may not do the right thing:
@@ -279,6 +304,7 @@ typedef U64TYPE U64;
279304
#define nBIT_UMAX(n) nBIT_MASK(n)
280305

281306
/*
307+
=for apidoc_section Compiler directives
282308
=for apidoc Am|void|__ASSERT_|bool expr
283309
284310
This is a helper macro to avoid preprocessor issues, replaced by nothing
@@ -300,7 +326,7 @@ detects that and gets all excited. */
300326
#endif
301327

302328
/*
303-
=head1 SV Manipulation Functions
329+
=for apidoc_section SV Handling
304330
305331
=for apidoc Ama|SV*|newSVpvs|"literal string"
306332
Like C<newSVpvn>, but takes a literal string instead of a
@@ -342,7 +368,7 @@ string/length pair.
342368
Like C<sv_setref_pvn>, but takes a literal string instead of
343369
a string/length pair.
344370
345-
=head1 Memory Management
371+
=for apidoc_section String Handling
346372
347373
=for apidoc Ama|char*|savepvs|"literal string"
348374
Like C<savepvn>, but takes a literal string instead of a
@@ -352,13 +378,13 @@ string/length pair.
352378
A version of C<savepvs()> which allocates the duplicate string in memory
353379
which is shared between threads.
354380
355-
=head1 GV Functions
381+
=for apidoc_section GV Handling
356382
357383
=for apidoc Am|HV*|gv_stashpvs|"name"|I32 create
358384
Like C<gv_stashpvn>, but takes a literal string instead of a
359385
string/length pair.
360386
361-
=head1 Hash Manipulation Functions
387+
=for apidoc_section HV Handling
362388
363389
=for apidoc Am|SV**|hv_fetchs|HV* tb|"key"|I32 lval
364390
Like C<hv_fetch>, but takes a literal string instead of a
@@ -380,7 +406,7 @@ a string/length pair.
380406
*/
381407

382408
/*
383-
=head1 Handy Values
409+
=for apidoc_section String Handling
384410
385411
=for apidoc Amu|pair|STR_WITH_LEN|"literal string"
386412
@@ -455,6 +481,7 @@ Perl_xxx(aTHX_ ...) form for any API calls where it's used.
455481
PERL_VERSION_PATCH)
456482

457483
/*
484+
=for apidoc_section Versioning
458485
=for apidoc AmR|bool|PERL_VERSION_EQ|const U8 major|const U8 minor|const U8 patch
459486
460487
Returns whether or not the perl currently being compiled has the specified
@@ -529,7 +556,7 @@ becomes
529556
# define PERL_VERSION_GT(j,n,p) (! PERL_VERSION_LE(j,n,p))
530557

531558
/*
532-
=head1 Miscellaneous Functions
559+
=for apidoc_section String Handling
533560
534561
=for apidoc Am|bool|strNE|char* s1|char* s2
535562
Test two C<NUL>-terminated strings to see if they are different. Returns true
@@ -1153,7 +1180,7 @@ C<isIDCONT_LC_utf8>, and C<isIDCONT_LC_utf8_safe>.
11531180
=for apidoc Amh|bool|isIDCONT_LC_uvchr|int ch
11541181
=for apidoc Amh|bool|isIDCONT_LC_utf8_safe|U8 * s| U8 *end
11551182
1156-
=head1 Miscellaneous Functions
1183+
=for apidoc_section Numeric Functions
11571184
11581185
=for apidoc Am|U8|READ_XDIGIT|char str*
11591186
Returns the value of an ASCII-range hex digit and advances the string pointer.
@@ -1340,6 +1367,7 @@ patched there. The file as of this writing is cpan/Devel-PPPort/parts/inc/misc
13401367

13411368
/*
13421369
void below because that's the best fit, and works for Devel::PPPort
1370+
=for apidoc_section Integer configuration values
13431371
=for apidoc AmnU|void|WIDEST_UTYPE
13441372
13451373
Yields the widest unsigned integer type on the platform, currently either
@@ -2485,6 +2513,7 @@ The XSUB-writer's interface to the C C<free> function.
24852513
24862514
This should B<ONLY> be used on memory obtained using L</"Newx"> and friends.
24872515
2516+
=for apidoc_section String Handling
24882517
=for apidoc Am|void|Move|void* src|void* dest|int nitems|type
24892518
The XSUB-writer's interface to the C C<memmove> function. The C<src> is the
24902519
source, C<dest> is the destination, C<nitems> is the number of items, and
@@ -2517,6 +2546,7 @@ Like C<Zero> but returns dest. Useful
25172546
for encouraging compilers to tail-call
25182547
optimise.
25192548
2549+
=for apidoc_section Utility Functions
25202550
=for apidoc Am|void|StructCopy|type *src|type *dest|type
25212551
This is an architecture-independent macro to copy one structure to another.
25222552
@@ -2731,7 +2761,7 @@ void Perl_mem_log_del_sv(const SV *sv, const char *filename, const int linenumbe
27312761
#define StructCopy(s,d,t) (*((t*)(d)) = *((t*)(s)))
27322762

27332763
/*
2734-
=head1 Handy Values
2764+
=for apidoc_section Utility Functions
27352765
27362766
=for apidoc Am|STRLEN|C_ARRAY_LENGTH|void *a
27372767

‎hv.c

+3-1
Original file line numberDiff line numberDiff line change
@@ -17,7 +17,7 @@
1717
*/
1818

1919
/*
20-
=head1 Hash Manipulation Functions
20+
=head1 HV Handling
2121
A HV structure represents a Perl hash. It consists mainly of an array
2222
of pointers, each of which points to a linked list of HE structures. The
2323
array is indexed by the hash function of the key, so each linked list
@@ -3731,6 +3731,7 @@ Perl_refcounted_he_inc(pTHX_ struct refcounted_he *he)
37313731
}
37323732

37333733
/*
3734+
=for apidoc_section COP Hint Hashes
37343735
=for apidoc cop_fetch_label
37353736
37363737
Returns the label attached to a cop, and stores its length in bytes into
@@ -3810,6 +3811,7 @@ Perl_cop_store_label(pTHX_ COP *const cop, const char *label, STRLEN len,
38103811
}
38113812

38123813
/*
3814+
=for apidoc_section HV Handling
38133815
=for apidoc hv_assert
38143816
38153817
Check that a hash is in an internally consistent state.

‎hv.h

+1-5
Original file line numberDiff line numberDiff line change
@@ -140,22 +140,18 @@ struct xpvhv {
140140
};
141141

142142
/*
143-
=head1 Hash Manipulation Functions
143+
=for apidoc_section HV Handling
144144
145145
=for apidoc AmnU||HEf_SVKEY
146146
This flag, used in the length slot of hash entries and magic structures,
147147
specifies the structure contains an C<SV*> pointer where a C<char*> pointer
148148
is to be expected. (For information only--not to be used).
149149
150-
=head1 Handy Values
151-
152150
=for apidoc ADmnU||Nullhv
153151
Null HV pointer.
154152
155153
(deprecated - use C<(HV *)NULL> instead)
156154
157-
=head1 Hash Manipulation Functions
158-
159155
=for apidoc Am|char*|HvNAME|HV* stash
160156
Returns the package name of a stash, or C<NULL> if C<stash> isn't a stash.
161157
See C<L</SvSTASH>>, C<L</CvSTASH>>.

‎inline.h

+5-2
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ SOFTWARE.
4040
/* ------------------------------- av.h ------------------------------- */
4141

4242
/*
43+
=for apidoc_section AV Handling
4344
=for apidoc av_count
4445
Returns the number of elements in the array C<av>. This is the true length of
4546
the array, including any undefined elements. It is always the same as
@@ -1876,7 +1877,7 @@ Perl_utf8_to_uvchr_buf_helper(pTHX_ const U8 *s, const U8 *send, STRLEN *retlen)
18761877
/* ------------------------------- perl.h ----------------------------- */
18771878

18781879
/*
1879-
=head1 Miscellaneous Functions
1880+
=for apidoc_section Utility Functions
18801881
18811882
=for apidoc is_safe_syscall
18821883
@@ -2449,7 +2450,7 @@ Perl_cx_popgiven(pTHX_ PERL_CONTEXT *cx)
24492450
/* ------------------ util.h ------------------------------------------- */
24502451

24512452
/*
2452-
=head1 Miscellaneous Functions
2453+
=for apidoc_section String Handling
24532454
24542455
=for apidoc foldEQ
24552456
@@ -2505,6 +2506,7 @@ Perl_foldEQ_latin1(const char *s1, const char *s2, I32 len)
25052506
}
25062507

25072508
/*
2509+
=for apidoc_section Locales
25082510
=for apidoc foldEQ_locale
25092511
25102512
Returns true if the leading C<len> bytes of the strings C<s1> and C<s2> are the
@@ -2532,6 +2534,7 @@ Perl_foldEQ_locale(const char *s1, const char *s2, I32 len)
25322534
}
25332535

25342536
/*
2537+
=for apidoc_section String Handling
25352538
=for apidoc my_strnlen
25362539
25372540
The C library C<strnlen> if available, or a Perl implementation of it.

‎locale.c

+1-1
Original file line numberDiff line numberDiff line change
@@ -2281,7 +2281,7 @@ S_win32_setlocale(pTHX_ int category, const char* locale)
22812281

22822282
/*
22832283
2284-
=head1 Locale-related functions and macros
2284+
=for apidoc_section Locales
22852285
22862286
=for apidoc Perl_setlocale
22872287

‎malloc.c

+1
Original file line numberDiff line numberDiff line change
@@ -1225,6 +1225,7 @@ S_adjust_size_and_find_bucket(size_t *nbytes_p)
12251225
/*
12261226
These have the same interfaces as the C lib ones, so are considered documented
12271227
1228+
=for apidoc_section Memory Management
12281229
=for apidoc malloc
12291230
=for apidoc calloc
12301231
=for apidoc realloc

0 commit comments

Comments
 (0)