From: Jim Cromie <jcromie@cpan.org>
Date: Sun, 8 Jan 2006 11:35:46 +0000 (-0700)
Subject: [patch] more about embed.fnc in perlguts
X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=commitdiff_plain;h=1aa6ea502f811472fe5fb23153ef6b09b3f470ec;p=p5sagit%2Fp5-mst-13.2.git

[patch] more about embed.fnc in perlguts
Message-ID: <43C15B82.9090309@gmail.com>

(with a few nits)

p4raw-id: //depot/perl@26756
---

diff --git a/embed.fnc b/embed.fnc
index b32be40..b54969d 100644
--- a/embed.fnc
+++ b/embed.fnc
@@ -11,7 +11,7 @@
 :	d		function has documentation with its source
 :	s		static function, should have an S_ prefix in
 :			source file; for macros (m), suffix the usage
-:			example	with a semicolon
+:			example with a semicolon
 :	n		has no implicit interpreter/thread context argument
 :	p		function has a Perl_ prefix
 :	f		function takes printf style format string, varargs
@@ -28,6 +28,7 @@
 :	R		Return value must not be ignored.
 :	P		pure function: no effects except the return value;
 :			return value depends only on parms and/or globals
+: (see also L<perlguts/Internal Functions> for those flags.)
 :
 : Pointer parameters that must not be passed NULLs should be prefixed with NN.
 :
diff --git a/pod/perlguts.pod b/pod/perlguts.pod
index d37a381..7d1392a 100644
--- a/pod/perlguts.pod
+++ b/pod/perlguts.pod
@@ -126,11 +126,11 @@ Also remember that C doesn't allow you to safely say C<foo(SvPV(s, len),
 len);>. It might work with your compiler, but it won't work for everyone.
 Break this sort of statement up into separate assignments:
 
-	SV *s;
-	STRLEN len;
-	char * ptr;
-	ptr = SvPV(s, len);
-	foo(ptr, len);
+    SV *s;
+    STRLEN len;
+    char * ptr;
+    ptr = SvPV(s, len);
+    foo(ptr, len);
 
 If you want to know if the scalar value is TRUE, you can use:
 
@@ -2184,16 +2184,18 @@ after that are the arguments. The first column is a set of flags:
 
 =item A
 
-This function is a part of the public API.
+This function is a part of the public API. All such functions should also
+have 'd', very few do not.
 
 =item p
 
-This function has a C<Perl_> prefix; i.e. it is defined as C<Perl_av_fetch>
+This function has a C<Perl_> prefix; i.e. it is defined as
+C<Perl_av_fetch>.
 
 =item d
 
 This function has documentation using the C<apidoc> feature which we'll
-look at in a second.
+look at in a second.  Some functions have 'd' but not 'A'; docs are good.
 
 =back
 
@@ -2203,12 +2205,13 @@ Other available flags are:
 
 =item s
 
-This is a static function and is defined as C<S_whatever>, and usually
-called within the sources as C<whatever(...)>.
+This is a static function and is defined as C<STATIC S_whatever>, and
+usually called within the sources as C<whatever(...)>.
 
 =item n
 
-This does not use C<aTHX_> and C<pTHX> to pass interpreter context. (See
+This does not need a interpreter context, so the definition has no
+C<pTHX>, and it follows that callers don't use C<aTHX>.  (See
 L<perlguts/Background and PERL_IMPLICIT_CONTEXT>.)
 
 =item r
@@ -2253,6 +2256,10 @@ This function is visible to extensions included in the Perl core.
 Binary backward compatibility; this function is a macro but also has
 a C<Perl_> implementation (which is exported).
 
+=item others
+
+See the comments at the top of C<embed.fnc> for others.
+
 =back
 
 If you edit F<embed.pl> or F<embed.fnc>, you will need to run
@@ -2596,7 +2603,7 @@ define your own ops. This is primarily to allow the building of
 interpreters for other languages in the Perl core, but it also allows
 optimizations through the creation of "macro-ops" (ops which perform the
 functions of multiple ops which are usually executed together, such as
-C<gvsv, gvsv, add>.) 
+C<gvsv, gvsv, add>.)
 
 This feature is implemented as a new op type, C<OP_CUSTOM>. The Perl
 core does not "know" anything special about this op type, and so it will