Add documentation.

p4raw-id: //depot/perl@12808

3 files changed, 50 insertions, 1 deletions

diff --git a/embed.pl b/embed.pl
index 42b714ba1c..37b2cbd084 100755
--- a/embed.pl
+++ b/embed.pl
@@ -1819,7 +1819,7 @@ Ap	|SV*	|swash_init	|char* pkg|char* name|SV* listsv \
 Ap	|UV	|swash_fetch	|SV *sv|U8 *ptr|bool do_utf8
 Ap	|void	|taint_env
 Ap	|void	|taint_proper	|const char* f|const char* s
-Ap	|UV	|to_utf8_case	|U8 *p|U8* ustrp|STRLEN *lenp \
+Apd	|UV	|to_utf8_case	|U8 *p|U8* ustrp|STRLEN *lenp \
 				|SV **swash|char *normal|char *special
 Ap	|UV	|to_utf8_lower	|U8 *p|U8* ustrp|STRLEN *lenp
 Ap	|UV	|to_utf8_upper	|U8 *p|U8* ustrp|STRLEN *lenp
diff --git a/pod/perlapi.pod b/pod/perlapi.pod
index 89894fcd36..e01489ab49 100644
--- a/pod/perlapi.pod
+++ b/pod/perlapi.pod
@@ -4229,6 +4229,31 @@ Converts the specified character to uppercase.
 =for hackers
 Found in file handy.h
 
+=item to_utf8_case
+
+The "p" contains the pointer to the UTF-8 string encoding
+the character that is being converted.
+
+The "ustrp" is a pointer to the character buffer to put the
+conversion result to.  The "lenp" is a pointer to the length
+of the result.
+
+The "swash" is a pointer to the swash to use.
+
+The "normal" is a string like "ToLower" which means the swash
+$utf8::ToLower, which is stored in lib/unicore/To/Lower.pl,
+and loaded by SWASHGET, using lib/utf8_heavy.pl.
+
+The "special" is a string like "utf8::ToSpecLower", which means
+the hash %utf8::ToSpecLower, which is stored in in the same file,
+lib/unicore/To/Lower.pl, and also loaded by SWASHGET.  The access
+to the hash is by Perl_to_utf8_case().
+
+	UV	to_utf8_case(U8 *p, U8* ustrp, STRLEN *lenp, SV **swash, char *normal, char *special)
+
+=for hackers
+Found in file utf8.c
+
 =item utf8n_to_uvchr
 
 Returns the native character value of the first character in the string C<s>
diff --git a/utf8.c b/utf8.c
index 768db078b8..407d382dcc 100644
--- a/utf8.c
+++ b/utf8.c
@@ -1180,6 +1180,30 @@ Perl_is_utf8_mark(pTHX_ U8 *p)
     return swash_fetch(PL_utf8_mark, p, TRUE);
 }
 
+/*
+=for apidoc A|UV|to_utf8_case|U8 *p|U8* ustrp|STRLEN *lenp|SV **swash|char *normal|char *special
+
+The "p" contains the pointer to the UTF-8 string encoding
+the character that is being converted.
+
+The "ustrp" is a pointer to the character buffer to put the
+conversion result to.  The "lenp" is a pointer to the length
+of the result.
+
+The "swash" is a pointer to the swash to use.
+
+The "normal" is a string like "ToLower" which means the swash
+$utf8::ToLower, which is stored in lib/unicore/To/Lower.pl,
+and loaded by SWASHGET, using lib/utf8_heavy.pl.
+
+The "special" is a string like "utf8::ToSpecLower", which means
+the hash %utf8::ToSpecLower, which is stored in in the same file,
+lib/unicore/To/Lower.pl, and also loaded by SWASHGET.  The access
+to the hash is by Perl_to_utf8_case().
+
+=cut
+ */
+
 UV
 Perl_to_utf8_case(pTHX_ U8 *p, U8* ustrp, STRLEN *lenp, SV **swashp,char *normal, char *special)
 {