PHP Documentation

Within PHPStorm IDE I can bring up documentation on "standard" PHP methods and properties using Ctrl-Q. Can I hook into this using custom classes and methods beyond showing the file name that it is defined in? What determines what 'Ctrl-Q' shows as 'documentation'?

10 comments
Comment actions Permalink

Hi there,

Ctrl+Click on any opf such standard functions/classes and see how it's done yourself.

In short: PHPDoc powered stub files (declaration of function/class written in PHP with empty body together with appropriate PHPDoc comment) -- that's how ALL known  by default to PhpStorm PHP-related stuff is defined.

Here is an example:

/**
* (PHP 4, PHP 5)<br/>
* Return current Unix timestamp with microseconds
* @link http://php.net/manual/en/function.microtime.php
* @param bool $get_as_float [optional] <p>
* When called without the optional argument, this function returns the string
* "msec sec" where sec is the current time measured in the number of
* seconds since the Unix Epoch (0:00:00 January 1, 1970 GMT), and
* msec is the microseconds part.
* Both portions of the string are returned in units of seconds.
* </p>
* <p>
* If the optional get_as_float is set to
* true then a float (in seconds) is returned.
* </p>
* @return mixed
*/
function microtime ($get_as_float = null) {}

0
Comment actions Permalink

Any PHPDoc comments you have for functions and classes within code that is part of your project should show up in the popup.

     /**
     * Allows for the addition of custom scripting to the header.
     * @param string $script The custom script to include
     */
    public static function addCustomScript($script)
    {
        self::$customScript[] = $script;
    }

This function shows up properly annotated in the popup as would any native function.

0
Comment actions Permalink

When I put comments in this form on the method I just get a 'Method reference' when I hit CTRL-Q. And the reference seems to be wrong.

0
Comment actions Permalink

Can you please illustrate this with screenshot .. as I could not understand what you mean here.

0
Comment actions Permalink

I have attached three screenshots. The first is the output that I get from the IDE when I type CTRL-Q. The second is the function that I am positioned at when I type CTRL-Q. The third is the 'documentation' comments associated with the function.

Thank you.

Kevin



Attachment(s):
doc3.jpg
doc2.jpg
doc1.jpg
0
Comment actions Permalink

What do you see when you Ctrl+Q on $soapclient ? How it is declared in the class?

Is QueryPresentations on that line is highlighted in any way (in other words -- any warnings/notices)?

0
Comment actions Permalink

What happens if you press ctrl-q on the field referernce.

eg.
self::$soapclient

Can it determine type accutately( not object/mixed etc )?

That phpdoc can appear like that if the field is not properly phpdocced/cannot calculate type eg.
ctrl q will wok on the $this->aTest1->testDoc()

<?php

namespace Trident\DocParser;


class ATest {

    /** @var  ATest  */
    private $aTest1;

    private $aTest2;

    function __construct() {
        $this->aTest1->testDoc( '' ); //works
        $this->aTest2->testDoc( '' ); //will not show phpdoc
    }


    /**
     * @param $param
     */
    public function testDoc( $param ) {

    }

}

0
Comment actions Permalink

I have included four more screen shots. The first is when I highlight $soapclient and type CTRL-Q. This is not quite correct. There is an inheritance structure that is missing. The second shows the highlight on $soapclient when I type CTRL-Q. The third screenshot show the declaration of the variable. The fourth shows the initialization of the variable.

Kevin



Attachment(s):
doc7.jpg
doc6.jpg
doc5.jpg
doc4.jpg
0
Comment actions Permalink

Yes, it's expected behaviour.

1) IDE does not know what $soapclient is
2) As result it marks QueryPresentations method as unknown (yellowish backgound)

Adding PHPDoc for $soapclient field should do the job just fine:

/** @var \Sonicfoundry\MediasiteClient Optional description */

private static $soapclient;


BTW -- why field is static, especially in PHPUnit test case?

0
Comment actions Permalink

Thank you that is what i was looking for.

It is static because the function initializing it is static (setupBeforeClass).

0

Please sign in to leave a comment.