phpDocs Script

Rain · May 15, 2007#12007-05-15T06:13+00:00

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

Askahain · Oct 28, 2010#22010-10-28T07:14+00:00

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 ?

jorrasdk · Oct 28, 2010#32010-10-28T08:48+00:00

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();

Askahain · Oct 28, 2010#42010-10-28T10:32+00:00

Thank you very much

echopark · Aug 04, 2011#52011-08-04T09:21+00:00

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();

Mofi · Aug 04, 2011#62011-08-04T12:00+00:00

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]*/);

phpDocs Script

phpDocs Script

phpDocs Script

Choose Display Mode