phpDoc, included files and documentation lookup problems

Hi!

Is there a way for PhpStorm to show documentation for user defined methods that have been included using e.g. include_once()?

So far I've only been able to successfully present documentation lookup when the method's phpDoc is residing in the same file, which is very limiting when trying to understand what a method does, especially when it has been included from another file.
What seems to be working ok, which is as I expect, is that I can invoke code completion by typing a part of the same method's name, then hitting Command+Space and get a suggestion of the method I want, along with a very short hand documentation description of its arguments.

I've been banging my head at this problem for half an hour now and would like to know if there is any way at all that accomplishes what I want to do, which is to display documentation for methods that are globally available.

Thank you!

/shellström

7 comments
Comment actions Permalink

Hi there,

Could you please illustrate your problem with some sample simple code?

Right now I simply do not understand what problem you are having here as IDE is very capable of showing documentation for functions regardless of include/require statements.

What seems to be working ok, which is as I expect, is that I can invoke code completion by typing a part of the same method's name, then hitting Command+Space and get a suggestion of the method I want, along with a very short hand documentation description of its arguments.

You can have both: shortcut for "View | Quick Documentation" is working inside code completion popup as well.

screen01.png

0
Comment actions Permalink

Thank you for your swift response, Andriy.

Alright, it may be that PhpStorm needs an object as a reference first. The file structure and pseudo-code I have is more like this:

====================

/folder/subfolder/file1.php
<?php

/**
* Some doc here
*
* @param int $intOne This is int one
* @param int $intTwo This is int two
* @return int The sum
*/
function getSum($intOne, $intTwo) {
//Code here
}

/folder/file2.php
<?php
include_once(subfolder/file1.php);

$aSum = getSum(1, 2);

=====================

As you can see, there are no classes or objects referenced, just the function itself, at the root. But I cannot, when trying to invoke the documentation lookup, get the documentation for file1.php:getSum. It only shows me a window that refers to itself in the Source.
Maybe I'm doing this wrong, but if the function was defined and documented in file2.php instead of file1, PhpStorm will display the documentation.



Attachment(s):
documentation_lookup.png
0
Comment actions Permalink

I'm terribly sorry but I still do not understand what kind of problem you are having. This is what I see when I use your sample files:
screen01.png


1) Could you please illustrate your problem using your sample files (preferably so that I can see editor tabs/folder structure as well) -- your screenshot shows different functions,

2) Before that -- please try "File | Invalidate Caches..." and restart IDE. Any better?

0
Comment actions Permalink

Hmmm, no need to be sorry. I wanted to illustrate how the code was structured and how the execution went without having to include so much of the code as it would add so much noise.
What I did do however, was to start an entirely clean project with only the two snippets of code I provided, in a similar folder structure and PhpStorm picked that up without any issues.

I will have to try and test this on a new imported project from the source and see if that changes anything.
Invalidating the caches unfortunately didn't help. I'll dig further into this and see what I can find. I'll accept your first answer, because PhpStorm does figure this out, it's just that it seems to be some oddities with the project I need to get working. :)

0
Comment actions Permalink

I think figured it out.

So, this project I'm working on contains a lot of symlinks to different places in the filesystem. It just so happens that a couple of these symlinks are pointing to the same source/physical folder. This, in turn, makes PhpStorm index these sources for code, and, because it expands the symlinks and thereby scanning the content of the symlink folder, create references to all instances of the same file(s) it can find.

This seems to confuse the lookup tool, which does not seem to be able to figure out which file is the valid one to open for showing its documentation and "gives up".
When I excluded the symlinks and PhpStorm reindexed the content, the documentation showed up as I would have expected.

Interesting, and a little bit tricky to catch. I will have slightly more time to verify my findings tomorrow. I don't know if this would be considered a bug or something for a feature request update, to have PhpStorm handle these kinds of situationss?

0
Comment actions Permalink
This seems to confuse the lookup tool, which does not seem to be able to figure out which file is the valid one to open for showing its documentation and "gives up".

Next time check such situations with Ctrl+Click (Navigate | Declaration) -- in such case IDE should show you a list of all possible locations .. which means that you have the same stuff declared more than once in your project.

With classes it's a bit easier -- IDE highlights classes with multiple declarations (weak warning; not too visible but good enough as in some cases it's the way how frameworks work (e.g. Kohana)).

Plus, some standard PHP functions that have multiple syntaxes are declared few times in different stub files (currently the only way to show such functions as separate entries in code completion -- that's how indexing engine works ATM)

When I excluded the symlinks

Using PhpStorm's "Mark as Excluded" functionality on folder?

I don't know if this would be considered a bug or something for a feature request update, to have PhpStorm handle these kinds of situationss?

Devs are fully aware of such behaviour (I mean: the fact that IDE gets confused with multiple declarations, especially if they differ even a bit). Obviously, ideally it should not be happening like that  and IDE should be either more clever and show at least something .. or show clearly visible warning/notification that other implementations are available and could differ from currently displayed)


You can watch these tickets (star/vote/comment) to get notified on progress.

0
Comment actions Permalink

Bazzik wrote:

Using PhpStorm's "Mark as Excluded" functionality on folder?

Yes, correct.

Bazzik wrote:

Devs are fully aware of such behaviour... 
...You can watch these tickets (star/vote/comment) to get notified on progress.

Alright. I found no starring functionality (at least not on mobile) so did +1's on them.

Since my problem is not 100% matching any of them, but seem to have the same core issue, is it of any value to create a separate report?

0

Please sign in to leave a comment.