autodoc.pl: Make 's' flag independent of 'n'

The 's' flag is used by autodoc.pl to add a semi-colon to the end of a
usage example.  This commit allows that to happen even if the macro has
parameters.

This allows two macros in scope.c to be properly documented.  Previously
they weren't, and caused warnings in Devel::PPPort as a result.

This commit adds documentation to embed.fnc for the 's' flag, which has
long existed, undocumented.

diff --git a/autodoc.pl b/autodoc.pl
index 2d56e81..9a2e9ec 100644 (file)
--- a/autodoc.pl
+++ b/autodoc.pl
@@ -221,11 +221,10 @@ removed without notice.\n\n$docs" if $flags =~ /x/;
     print $fh "=item $name\nX<$name>\n$docs";
 
     if ($flags =~ /U/) { # no usage
+        warn("U and s flags are incompatible") if $flags =~ /s/;
        # nothing
     } else {
-        if ($flags =~ /s/) { # semicolon ("dTHR;")
-            print $fh "\t\t$name;";
-        } elsif ($flags =~ /n/) { # no args
+        if ($flags =~ /n/) { # no args
             print $fh "\t$ret\t$name";
         } else { # full usage
             my $n            = "Perl_"x$p . $name;
@@ -271,6 +270,7 @@ removed without notice.\n\n$docs" if $flags =~ /x/;
             if ($long_args) { print $fh "\n", substr $indent, 0, -4 }
             print $fh ")";
         }
+        print $fh ";" if $flags =~ /s/; # semicolon "dTHR;"
         print $fh "\n\n";
     }
     print $fh "=for hackers\nFound in file $file\n\n";

diff --git a/embed.fnc b/embed.fnc
index 46a570c..4c444ea 100644 (file)
--- a/embed.fnc
+++ b/embed.fnc
@@ -171,6 +171,9 @@
 :                STATIC is added to declaration;
 :         embed.h: "#define foo S_foo" entries added
 :
+:   s  autodoc.pl adds a terminating semi-colon to the usage example in the
+:      documentation.
+:
 :   T  Has no implicit interpreter/thread context argument:
 :
 :         suppress the pTHX part of "foo(pTHX...)" in proto.h;

diff --git a/scope.h b/scope.h
index f2dcef0..5fde315 100644 (file)
--- a/scope.h
+++ b/scope.h
@@ -167,12 +167,12 @@ Opening bracket on a callback.  See C<L</LEAVE>> and L<perlcall>.
 =for apidoc Amns||LEAVE
 Closing bracket on a callback.  See C<L</ENTER>> and L<perlcall>.
 
-=for apidoc Ams||ENTER_with_name(name)
+=for apidoc Ams||ENTER_with_name|const char * name
 
 Same as C<L</ENTER>>, but when debugging is enabled it also associates the
 given literal string with the new scope.
 
-=for apidoc Ams||LEAVE_with_name(name)
+=for apidoc Ams||LEAVE_with_name|const char * name
 
 Same as C<L</LEAVE>>, but when debugging is enabled it first checks that the
 scope has the given name. C<name> must be a literal string.