I use Eclipse for PHP development and really appreciate the productivity gain. I am a javadoc comment zealot too because the code hinting and autocompletion really speed things up and reduce errors in code.

Can anyone tell me how to write a javadoc comment for @return when my function returns an array of class objects? When I iterate through the array, I want Eclipse to give me code hints for each returned object.

For example, here's one of my class functions in a class called BCDataObject:

	/**
	 * Fetches all data records from the db table.
	 * @param CI_DB_driver $db CodeIgniter JDatabase object to access database
	 * @return multitype:BCDataObject
	 */
	public static function fetch_all($db) {
		$query = $db->get(static::DATABASE_TABLE);

	$results = array();
	foreach ($query->result_array() as $record) {
		$results[] = new static($db, $record);
	}
	return $results;
} // fetch_all()

I know that Eclipse is smart enough to recognize that the function returns a collection of objects because it automatically created this boilerplate javadoc when I first created the javadoc block by typing a slash and two asterisks and hitting return. In fact, this is the doc block auto-created by eclipse:

/**
 * 
 * @param unknown_type $db
 * @return multitype:BCDataObject
 */

The problem I have is that when I go to a place where I am using this code, I can use my function to get the array of objects but when I do a foreach loop on the result, Eclipse doesn't seem to know the type of the objects I am iterating so I don't get autocomplete or code hinting. For example, in this block of code:

$v = BCDataObject::fetch_all($this->db);
foreach($v as $user) {
  echo $user . "<br>";
}

Eclipse doesn't give me code hints or autocomplete for the var $user -- for some reason it fails to recognize that each element of $v will be of type BCDataObject.

Can anyone tell me how to create my javadoc so I get this type of code hinting? Is it possible? If I could get that working, it would rule.

    While I don't use eclipse, I just add [] to the end of whatever type my array contains to make it work in phpstorm. No idea if it's standard or not though.

      Thanks for your response, johanafm. I think the brackets may well be standard (and this sort of thing may well differ by IDE).

      As I mentioned in my post, I have noticed that Eclipse is smart enough to sniff out when you are returning an array of something because it will suggest an @return comment containing the word 'multitype'.

      I posted this same question in the Eclipse forums and someone responded that the latest PDT (3.2?) supports this functionality properly. Someone else also suggested the use of brackets:
      http://www.eclipse.org/forums/index.php/t/556971/

      Looks like I need to finally upgrade.

        I swear I didn't dream this, but I can't find it anywhere now... There was a page in the docs about using [font=monospace]@type[/font] for variables (there are still some instances in examples), and using a nested docblock for array definitions. Similar to:

        @type array $myArray  a map of stuff {
            @type string $fav_color  your favorite color
            @type int    $fav_num    your favorite number
            @type array  $friends    a ranked list of friends {
                @type string $0  zero the hero
                @type string $1  first the worst
                @type string $2  etc ...
            }
        }

        no IDE support AFAIK, but I figured, hey, it looks good and support will come. But maybe they dropped it.

        = = = = = edit = = = = =
        Maybe @type was dropped because of conflicts with Doctrine conventions...?

        In any case, maybe I wasn't dreaming: this (missing) page is linked to from several different sources, with reference to the @type notation...

        = = = = = edit #2 = = = = =

        ah-hah! I love git

        /**
         * Initializes this class with the given options.
         *
         * @param string[] $options {
         *     @type boolean $required Whether this element is required
         *     @type string  $label    The display name for this element
         * }
         */
        public function __construct(array $options = array())
        {
            <...>
        }

        (Though I'm not sure why it says "string[]" - I seem to remember it saying "array[]".)

        It seems that they un-deprecated @var and dropped @type (and all reference to "describing hashes") sometime after v.2.0.2.

          Oh man I've never seen @type or @struct. I wonder if there is a standardized version of javadoc? I'm thinking if phpdocumentor differs from this standard they might be looking for trouble.

            5 days later

            Since Oracle took over Java from SUN, which invented Javadoc, that documentation is about as 'standard' as you can get. See the writeup for @ and @return.

            Of course, PHP is not Java; Java doesn't really need additional documentation hints for argument/return types, since they're already part of the method signature.

              Write a Reply...