Automatically add PHPDoc using existing comments

Question

I want to tidy a large function include file where PHPDoc is only used partially. there are some functions without PHPDoc like

function name($var1,$var2){ // explanation what it does
  # ...
}

and some where the PHPDoc exists but is incomplete like some variables missing:

/**
  * explanation
  *
  * @param boolean $var1 foo foo foo
  *
  * @return null
  */
function name2($var1,$var2){ 
  # ...
}

or just

/** explanation
  */
function name3($var1,$var2){ 
  # ...
}

How is it possible to add all missing variable definitions and return values, using a correct "unknown" tag for the ones added?

It could analyse each function if it has a return value and it should convert the already existing comments (behind each function) and use them in PHPDoc.

I am aware that you will have to check the result manually, but it would be really helpful to generate a skeleton with the data that already exists.

Answer 1

You could do it using a combination of Reflection, token_get_all which uses Zend's lexical scanner to parse a string into PHP lanugage tokens and quite possibly regular expressions.

The problem with Reflection is that some methods, like ReflectionFunctionAbstract::getReturnType are available only on PHP 7.

In PHP 5+ you can use ReflectionFunctionAbstract::getParameters, ReflectionFunctionAbstract::getDocComment etc.

If there's no DocBlock you could get the function start and end lines with ReflectionFunctionAbstract::getStartLine and ReflectionFunctionAbstract::getEndLine, copy the source block to a string and use token_get_all to obtain an array of PHP tokens to analyze individually.

Reflection example in PHP 5.6:

<?php

/**
 * explanation
 *
 * @param boolean $var1 foo foo foo
 *
 * @return null
 */
 function test($var1, $var2) {

 }

 echo ReflectionFunction::export('test', true);

Output:

/**
 * explanation
 *
 * @param boolean $var1 foo foo foo
 *
 * @return null
 */
Function [ <user> function test ] {
  @@ index.php 10 - 12

  - Parameters [2] {
    Parameter #0 [ <required> $var1 ]
    Parameter #1 [ <required> $var2 ]
  }
}

Answer 2

I hope this can be helpful for you.

As I am using sublime text editor. I installed DocBlockr. Here is link