phpDocs Script

phpDocs Script

1
NewbieNewbie
1

    May 15, 2007#1

    For anyone using phpDocs format to document their php Project this script file should be very useful.

    The script generates the docBlock code depending on the currently selected line.
    <?php: creates file-level block.
    class/var: creates an empty block for comments.
    function: automatically adds the listed parameters.
    existing comments: Asks for new phpDocs tag name

    The lastest version of the code can be found at

    phpDocs UltraEdit Script

    2
    NewbieNewbie
    2

      Oct 28, 2010#2

      The link is down.

      Is there a function in UE that help generating the docBlocks or is there an other script that can do it ?

      262
      MasterMaster
      262

        Oct 28, 2010#3

        I saved a copy of the script since it was released into the public domain on May 15th, 2007.

        Code: Select all

        // Script by. Rain Style http://www.rain.com.au
        //
        // TODO: Detect line terminators
        //
        // Add phpDocs comment style above a function declaration/definition.
        function phpDocFunc() {
          var doc = UltraEdit.activeDocument;
          var curline;
          doc.selectLine();
          curline = doc.selection;
          curline = curline.replace(/\r|\n/g," ");    			// remove line terminators if any.
        
          var indent = curline.match(/^[ \t]*/);
          indent = indent[0] ? indent[0] : "";
        
          if(curline.match(/<\?php/)) {
          	doc.key("UP ARROW");
          	doc.key("END");
        		doc.key("RIGHT ARROW");
          	var str = Array();
          	str.push(indent+'/**');
          	str.push('*');
          	str.push('* @package');
          	str.push('* @subpackage');
          	str.push('*/');
        
          	for(var i in str) {
          		doc.gotoLine(0,0);
          		doc.write(str[i]+'\r\n');
          		doc.key("HOME");
          	}
          }
          else if(curline.match(/class /)) {
          	doc.key("UP ARROW");
          	doc.write ("\r\n"); // only valid for dos eol!
          	doc.key("UP ARROW");
          	str = Array();
          	str.push(indent+'/**');
          	str.push('* ');
          	str.push('* ');
          	str.push('*/');
        
          	for(i in str) {
          		doc.gotoLine(0,0);
          		doc.write(str[i]+(i<str.length-1?'\r\n':''));
          	}
          }
          else if(curline.match(/var /)) {
          	doc.key("UP ARROW");
          	doc.write ("\r\n"); // only valid for dos eol!
          	doc.key("UP ARROW");
          	str = Array();
          	str.push(indent+'/**');
          	str.push('* ');
          	str.push('*/');
        
          	for(i in str) {
          		doc.gotoLine(0,0);
          		doc.write(str[i]+(i<str.length-1?'\r\n':''));
          	}
          }
          else if(curline.match(/function /)) {
        
          	  // get argument list (between parenthesis)
        		  var re = /\(.*\)/;
        		  var parens = curline.match(re);
        		  // Try to extract parameters from stuff between parenthesis.
        		  // Note that 'parens.match' (below) returns an array.
        		  var params = null;
        		  if (parens) {
        		    parens = parens[0];
        		    var param_re = /\w+(?=\s*[,\)])/g;
        		    params = parens.match(param_re);
        		  }
        
        
          	doc.key("UP ARROW");
          	doc.write ("\r\n"); // only valid for dos eol!
          	doc.key("UP ARROW");
          	str = Array();
          	str.push(indent+'/**');
          	str.push('* ');
          	str.push('* ');
        		if (params) {
            	for (i = 0; i < params.length; ++i) {
          			str.push('* @param '+params[i]);
        			}
        		}
          	str.push('* @return ');
          	str.push('*/');
          	for(i in str) {
          		doc.gotoLine(0,0);
          		doc.write(str[i]+(i<str.length-1?'\r\n':''));
          	}
          }
          else if(curline.match(/\*/)) {
          	var tag = UltraEdit.getString('Enter phpDoc tag:',1);
          	doc.key("UP ARROW");
          	doc.write ("\r\n"); // only valid for dos eol!
          	doc.key("UP ARROW");
          	str = Array();
          	str.push(indent+'* @'+tag+' ');
          	for(i in str) {
          		doc.gotoLine(0,0);
          		doc.write(str[i]+(i<str.length-1?'\r\n':''));
          	}
          }
          else {
          	doc.key("UP ARROW");
          	doc.write ("\r\n"); // only valid for dos eol!
          	doc.key("UP ARROW");
          	str = Array();
          	str.push(indent+'/**');
          	str.push('   * ');
          	str.push(' */');
        
          	for(i in str) {
          		doc.gotoLine(0,0);
          		doc.write(str[i]+(i<str.length-1?'\r\n':''));
          	}
          }
        
          return true;
        
        }
        // Execute function defined above
        phpDocFunc();

        2
        NewbieNewbie
        2

          Oct 28, 2010#4

          Thank you very much :)

          2
          NewbieNewbie
          2

            Aug 04, 2011#5

            You can replace "\r\n" and '\r\n' with a variable obtained via UltraEdit.activeDocument.lineTerminator:

            Code: Select all

            var sLineTerm = "\r\n";           // Default is DOS.
              if (typeof(UltraEdit.activeDocument.lineTerminator) == "number") {
                if (UltraEdit.activeDocument.lineTerminator == 2) sLineTerm = "\n";
                else if (UltraEdit.activeDocument.lineTerminator == 3) sLineTerm = "\r";
              }
            
            I also replaced the indent regex to match any space instead of tab only:

            Code: Select all

            var indent = curline.match(/^[\s]*/);
            
            I also had to replace str.push(' with str.push(indent+' to retain the indentation correctly.

            So here's my version of the script:

            Code: Select all

            // Script by. Rain Style http://www.rain.com.au
            //
            // Code to Detect line terminators code and indentation messing by Echopark
            //
            // Add phpDocs comment style above a function declaration/definition.
            function phpDocFunc() {
              var doc = UltraEdit.activeDocument;
              var curline;
              doc.selectLine();
              curline = doc.selection;
              curline = curline.replace(/\r|\n/g," ");             // remove line terminators if any.
              var sLineTerm = "\r\n";           // Default is DOS.
              if (typeof(UltraEdit.activeDocument.lineTerminator) == "number") {
                if (UltraEdit.activeDocument.lineTerminator == 2) sLineTerm = "\n";
                else if (UltraEdit.activeDocument.lineTerminator == 3) sLineTerm = "\r";
              }
            
              var indent = curline.match(/^[\s]*/);
                   
              indent = indent[0] ? indent[0] : "";
            
              if(curline.match(/<\?php/)) {
                 doc.key("UP ARROW");
                 doc.key("END");
                  doc.key("RIGHT ARROW");
                 var str = Array();
                 str.push(indent+'/**');
                 str.push(indent+'*');
                 str.push(indent+'* @package');
                 str.push(indent+'* @subpackage');
                 str.push(indent+'*/');
            
                 for(var i in str) {
                    doc.gotoLine(0,0);
                    doc.write(str[i]+sLineTerm);
                    doc.key("HOME");
                 }
              }
              else if(curline.match(/class /)) {
                 doc.key("UP ARROW");
                 doc.write (sLineTerm);
                 doc.key("UP ARROW");
                 str = Array();
                 str.push(indent+'/**');
                 str.push(indent+'* ');
                 str.push(indent+'* ');
                 str.push(indent+'*/');
            
                 for(i in str) {
                    doc.gotoLine(0,0);
                    doc.write(str[i]+(i<str.length-1?sLineTerm:''));
                 }
              }
              else if(curline.match(/var /)) {
                 doc.key("UP ARROW");
                 doc.write (sLineTerm);
                 doc.key("UP ARROW");
                 str = Array();
                 str.push(indent+'/**');
                 str.push(indent+'* ');
                 str.push(indent+'*/');
            
                 for(i in str) {
                    doc.gotoLine(0,0);
                    doc.write(str[i]+(i<str.length-1?sLineTerm:''));
                 }
              }
              else if(curline.match(/function /)) {
            
                   // get argument list (between parenthesis)
                    var re = /\(.*\)/;
                    var parens = curline.match(re);
                    // Try to extract parameters from stuff between parenthesis.
                    // Note that 'parens.match' (below) returns an array.
                    var params = null;
                    if (parens) {
                      parens = parens[0];
                      var param_re = /\w+(?=\s*[,\)])/g;
                      params = parens.match(param_re);
                    }
            
            
                 doc.key("UP ARROW");
                 doc.write (sLineTerm);
                 doc.key("UP ARROW");
                 str = Array();
                 str.push(indent+'/**');
                 str.push(indent+'* ');
                 str.push(indent+'* ');
                  if (params) {
                   for (i = 0; i < params.length; ++i) {
                       str.push(indent+'* @param '+params[i]);
                     }
                  }
                 str.push(indent+'* @return ');
                 str.push(indent+'*/');
                 for(i in str) {
                    doc.gotoLine(0,0);
                    doc.write(str[i]+(i<str.length-1?sLineTerm:''));
                 }
              }
              else if(curline.match(/\*/)) {
                 var tag = UltraEdit.getString('Enter phpDoc tag:',1);
                 doc.key("UP ARROW");
                 doc.write (sLineTerm);
                 doc.key("UP ARROW");
                 str = Array();
                 str.push(indent+'* @'+tag+' ');
                 for(i in str) {
                    doc.gotoLine(0,0);
                    doc.write(str[i]+(i<str.length-1?sLineTerm:''));
                 }
              }
              else {
                 doc.key("UP ARROW");
                 doc.write (sLineTerm);
                 doc.key("UP ARROW");
                 str = Array();
                 str.push(indent+'/**');
                 str.push(indent+'   * ');
                 str.push(indent+' */');
            
                 for(i in str) {
                    doc.gotoLine(0,0);
                    doc.write(str[i]+(i<str.length-1?sLineTerm:''));
                 }
              }
            
              return true;
            
            }
            // Execute function defined above
            phpDocFunc();
            

            6,603548
            Grand MasterGrand Master
            6,603548

              Aug 04, 2011#6

              Nice enhancements.

              But do you know that \s is not equal [ \t]. \s is a Shorthand Character Class for whitespace characters. And the space and horizontal tab characters are not the only whitespace characters. \s includes also other whitespace characters like carriage return \r, line-feed \n, vertical tab \v and form-feed \f.

              Well, vertical tab and form-feed are usually not present in PHP source files and that \s matches also the line terminating characters does not matter for the script as is, but I suggest nevertheless to use

              Code: Select all

                var indent = curline.match(/^[ \t]*/);