regen/embed.pl: Add checks that O flag used correctly

And add some comments in embed.fnc

Author: khwilliamson

embed.fnc

@@ -620,9 +620,11 @@
 :
 :   'O'  Has a perl_ compatibility macro.
 :
-:        The really OLD name for API funcs.
+:        The really OLD name for API funcs.  These now also require the 'p'
+:	 flag so as to generate a modern name.  Obviously no new entries
+:	 should get this flag.
 :
-:        autodoc.pl adds a note that the perl_ form of this function is
+:        autodoc.pl adds a note that the 'perl_' form of this function is
 :        deprecated.
 :
 :   'o'  Has no Perl_foo or S_foo compatibility macro:

regen/embed.pl

@@ -155,6 +155,11 @@ sub generate_proto_h {
             die_at_end "flag $1 is not legal (for function $plain_func)";
         }
 
+        if ($flags =~ /O/) {
+            die_at_end "$plain_func: O flag requires p flag" if $flags !~ /p/;
+            die_at_end "$plain_func: O flag forbids T flag" if $flags =~ /T/;
+        }
+
         my @nonnull;
         my $args_assert_line = ( $flags !~ /m/ );
         my $has_depth = ( $flags =~ /W/ );