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.

which framework or CMS you are using ? Or Core php ?

Monty Khanna
– Monty Khanna

2015-12-16 06:05:18 +00:00
Commented Dec 16, 2015 at 6:05 — Monty Khanna
– Monty Khanna, Commented Dec 16, 2015 at 6:05

aergistal · Accepted Answer · 2015-12-09 11:35:52Z

2

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 ]
  }
}

edited Dec 9, 2015 at 11:35

answered Dec 9, 2015 at 11:23

aergistal

31.4k5 gold badges76 silver badges98 bronze badges

Sign up to request clarification or add additional context in comments.

5 Comments

rubo77 Over a year ago

That sounds a lot of work. I rather thought about parsing the php file through awk and retrieve the comments and variable names this way

aergistal Over a year ago

@rubo77 Yes, without full Reflection it's hard. But awk won't help you with return types either.

rubo77 Over a year ago

It would help already to have a solution with just a dummy return value

rubo77 Over a year ago

this is not a solution, just a hint how to solve it with a lot of work. But since this is the only answer, and it probably would work if you invest several days of programming time, I will give the bonus here in 20 h, if there won't come up an easyer solution ;)

aergistal Over a year ago

@rubo77 Unfortunately the real solution involves a very large number of monkeys typing randomly on an equally large number of keyboards :)

Monty Khanna · Accepted Answer · 2015-12-16 16:45:03Z

1

+50

I hope this can be helpful for you.

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

answered Dec 16, 2015 at 16:45

Monty Khanna

1,1207 silver badges15 bronze badges

5 Comments

rubo77 Over a year ago

that helps a bit (like in eclipse), but you still have to type /** and ENTER to get a PHPDoc Block with the right amount of lines and you can jump with TAB to the next variable.And you have to add this fix: github.com/spadgos/sublime-jsdocs/issues/334

rubo77 Over a year ago

You should add my comment to your answer, otherwise it is only half the solution

Monty Khanna Over a year ago

@rubo77 : I think you did you checked issue date that is : Dec 10, 2014 by sameg14. After that many commit has been done on github. I tryed, i did not found this issue.

rubo77 Over a year ago

I have the issue still thats what i meant. On Ubuntu 15.10

Monty Khanna Over a year ago

Exception are always. :) But as i know editor is just IDE. it does not matter which OS you are using. Sublime Text is available for almost all OS's. If you are facing still this issue. It might be your sublime text plugins are not updated OR you are using two plugins for PHPDocs.

Collectives™ on Stack Overflow

Automatically add PHPDoc using existing comments

2 Answers 2

5 Comments

5 Comments

Hot Network Questions

Collectives™ on Stack Overflow

2 Answers 2

5 Comments

5 Comments

Related