[sipify] handles SIP_OUT arguments

remove them from parameters list and add them to return values

scripts/sipify.pl

@@ -58,6 +58,8 @@
 my $COMMENT_LAST_LINE_NOTE_WARNING = 0;
 my $COMMENT_CODE_SNIPPET = 0;
 my $COMMENT_TEMPLATE_DOCSTRING = 0;
+my @SKIPPED_PARAMS_OUT = ();
+my @SKIPPED_PARAMS_REMOVE = ();
 my $GLOB_IFDEF_NESTING_IDX = 0;
 my @GLOB_BRACKET_NESTING_IDX = (0);
 my $PRIVATE_SECTION_LINE = '';
@@ -372,6 +374,17 @@ sub remove_following_body_or_initializerlist {
 
 sub fix_annotations {
     my $line = $_[0];
+
+    # get removed params to be able to drop them out of the API doc
+    if ( $line =~ m/(\w+)\s+SIP_PYARGREMOVE/ ){
+      push @SKIPPED_PARAMS_REMOVE, $1;
+      dbg_info("caught removed param: $SKIPPED_PARAMS_REMOVE[$#SKIPPED_PARAMS_REMOVE]");
+    }
+    if ( $line =~ m/(\w+)\s+SIP_OUT/ ){
+      push @SKIPPED_PARAMS_OUT, $1;
+      dbg_info("caught removed param: $SKIPPED_PARAMS_OUT[$#SKIPPED_PARAMS_OUT]");
+    }
+
     # printed annotations
     $line =~ s/\/\/\s*SIP_ABSTRACT\b/\/Abstract\//;
     $line =~ s/\bSIP_ABSTRACT\b/\/Abstract\//;
@@ -453,6 +466,8 @@ sub detect_comment_block{
     $COMMENT_CODE_SNIPPET = 0;
     $COMMENT_LAST_LINE_NOTE_WARNING = 0;
     $FOUND_SINCE = 0;
+    @SKIPPED_PARAMS_OUT = ();
+    @SKIPPED_PARAMS_REMOVE = ();
     if ( $LINE =~ m/^\s*\/\*/ || $args{strict_mode} == UNSTRICT && $LINE =~ m/\/\*/ ){
         dbg_info("found comment block");
         do {no warnings 'uninitialized';
@@ -1183,13 +1198,48 @@ sub detect_non_method_member{
                 $doc_prepend = "\@DOCSTRINGSTEMPLATE\@" if $COMMENT_TEMPLATE_DOCSTRING == 1;
                 write_output("CM1", "$doc_prepend%Docstring\n");
                 my @comment_lines = split /\n/, $COMMENT;
+                my $skipping_param = 0;
+                my @out_params = ();
+                my $waiting_for_return_to_end = 0;
                 foreach my $comment_line (@comment_lines) {
                   # if ( $RETURN_TYPE ne '' && $comment_line =~ m/^\s*\.\. \w/ ){
                   #     # return type must be added before any other paragraph-level markup
                   #     write_output("CM5", ":rtype: $RETURN_TYPE\n\n");
                   #     $RETURN_TYPE = '';
                   # }
+                  if ( $comment_line =~ m/^:param\s+(\w+)/) {
+                    if ( $1 ~~ @SKIPPED_PARAMS_OUT || $1 ~~ @SKIPPED_PARAMS_REMOVE ) {
+                      if ( $1 ~~ @SKIPPED_PARAMS_OUT ) {
+                        $comment_line =~ s/^:param\s+(\w+):(.*)$/$1: $2/;
+                        push @out_params, $comment_line ;
+                      }
+                      $skipping_param = 1;
+                      next;
+                    }
+                  }
+                  if ( $skipping_param == 1 ) {
+                    if ( $comment_line =~ m/^(:.*|\.\..*|\s*)$/ ){
+                      $skipping_param = 0;
+                    }
+                    else {
+                      # exit_with_error('Skipped param (SIP_OUT) should have their doc on a single line');
+                    }
+                  }
                   write_output("CM2", "$doc_prepend$comment_line\n");
+                  if ( $comment_line =~ m/:return:/ && $#out_params >= 0 ){
+                    $waiting_for_return_to_end = 1;
+                    foreach my $out_param (@out_params) {
+                      write_output("CM7", "$doc_prepend         $out_param\n");
+                    }
+                  }
+                  if ( $waiting_for_return_to_end == 1 ) {
+                    if ($comment_line =~ m/^(:.*|\.\..*|\s*)$/) {
+                      $waiting_for_return_to_end = 0;
+                    }
+                    else {
+                      # exit_with_error('Return docstring should be single line with SIP_OUT params');
+                    }
+                  }
                   # if ( $RETURN_TYPE ne '' && $comment_line =~ m/:return:/ ){
                   #     # return type must be added before any other paragraph-level markup
                   #     write_output("CM5", ":rtype: $RETURN_TYPE\n\n");