phpDocs Script

[Rain]

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]

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]

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]

Thank you very much

[echopark]

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]

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