+: =for apidoc_item name
+:
+: followed by pod for that function. The purpose of these lines and the text
+: that immediately follows them is to furnish documentation for functions
+: and macros listed here in embed.fnc. 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 perlapi.pod from the
+: elements that are in the API (flagged as A in this file), and perlintern.pod
+: from the other elements.
+:
+: 'name' in the apidoc line corresponds to an item listed in this file, so that
+: the signature and flags need only be specified once, here, and automatically
+: they get placed into the generated pod.
+:
+: 'apidoc_item' is used for subsidiary entries, which share the same pod as the
+: plain apidoc one does. Thus the documentation for functions which do
+: essentially the same thing, but with minor differences can all be placed in
+: the same entry. The apidoc_item lines must all come after the apidoc line
+: and before the pod for the entry.
+:
+: The entries in this file that have corresponding '=for apidoc' entries must
+: have the 'd' flag set in this file.
+:
+: In C files, the apidoc lines are inside comment blocks. They may also be
+: placed in pod files. In those, the =for causes lines from there until the
+: next line beginning with an '=' to not be considered part of that pod.
+:
+: The 'h' flag is used to hide (suppress) the pod associated with =apidoc lines
+: from being placed in the generated perlapi or perlintern. There are several
+: reasons you might want to do this, given in the 'h' flag description below,
+: but one is for the case where the =apidoc occurs in a file that contains
+: regular pod. Without that flag, the associated pod will be placed in both
+: it, and perlapi or perlintern. That may be what you want, but it gives you
+: the flexibility to choose that, or instead have just a link to the source pod
+: inserted in perlapi or perlintern. This allows single-source browsing for
+: someone; they don't have to scan multiple pods trying to find something
+: suitable.
+:
+: There are also lines of this form scattered around the perl
+: source:
+:
+: =for apidoc_section Section Name
+: =head1 Section Name
+:
+: These aren't tied to this embed.fnc file, and so are documented in autodoc.pl.
+:
+: What goes into the documentation of a particular function ends with the next
+: line that begins with an '='. In particular, an '=cut' line ends that
+: documentation without introducing something new.
+:
+: Various macros and other elements aren't listed here in embed.fnc. They are
+: documented in the same manner, but since they don't have this file to get
+: information from, the defining lines have the syntax and meaning they do in
+: this file, so it can be specified:
+:
+: =for apidoc flags|return_type|name|arg1|arg2|...|argN
+: =for apidoc_item flags|return_type|name|arg1|arg2|...|argN