Integration With Eldoc Mode

[ejmr]

I want to see support for eldoc-mode within php-mode. But deciding how to approach that implementation is not trivial. Other people have already provided implementations on the Emacs Wiki and through various GitHub projects. Each implementation has its pros and cons.

One method relies on accessing the PHP documentation from the web in order to find the function signatures. I want to avoid any approach that requires the user to be online. As uncommon as I'm sure it is, I frequently work offline, even with languages like PHP. So any implementation that requires an Internet connection is a bust to me.

That approach can be turned around into using local documentation. But I do not know how common that is. I have no data to back this up, but I suspect very few PHP programmers keep a local copy of the official documentation on their computers.

Another idea is to use an auxilary PHP program. It would be a program that accepts a function, class name, et cetera, and uses PHP's reflection mechanisms to return a string of information to standard output, which php-mode could then prepare for eldoc-mode and pass along for display in the minibuffer. I feel like this is a more feasible approach than using local documentation because I do think most PHP programmers keep a copy of PHP on their own computers.

None of these approaches would support showing Eldoc information for user-defined functions. That would be the 'Killer Feature' to implement. In theory it could be done by running the user's PHP code and then using the reflection methods on that. But in practice that would be unsafe and ineffecient.

I am going to work on this in my spare time as a feature for the next version. But I would greatly appreciate any thoughts, ideas, and insights from other developers who have helped make php-mode what it is.

[ryuslash]

I usually have a very outdated version of the PHP documentation on my computer, if any.

Would it be an idea to look at either slime or geiser how they do it for lisp and scheme and see if that could be translated into something that works for PHP? I have been interested in finding out how they do it for a while...

[danlamanna]

I've been looking for something like this for a while and would love to see it in PHP mode, as of now I keep a copy of the documentation within my own configs.

I'm curious though how far you could go with it, for example in this branch on wordpress-mode I've been trying to integrate ctags and mimic a C-h f like help for PHP (see last 4 defuns) which seems to be working OK for the amount of time I've put into it.

Ideally I think the standard eldoc mode in the minibuffer would be amazing for general development, even more sophisticated would be the C-h f like interface, and even further, I think, would be if it could be implemented for local codebases using something like exuberant ctags.

[ejmr]

@ryuslash

Slime accomplishes it through Swank, their server component. It defines a framework, basically, for generating documentation from the code and Lisp envorinment. And then there are individual backends for various Lisp implementations which define describe-symbol-for-emacs and the related documentation functions to satisfy Swank. I don't know how Geiser does it, but I would guess something similar.

That approach works very well for a Lisp since we can continuously evaluate new forms, redefine previous definitions, modify the application as it's running, et cetera. It also helps that the format of Lisp code is not much more than an abstract syntax tree. PHP doesn't afford us those benefits. We can't selectively execute whatever parts of a PHP program we want, and while I know Facebook tackled converting PHP into an AST for HipHop that is not a road I want to go down if at all possible.

@danlamanna

Using ctags is definitely another possibility. That could be the easiest route just in terms of lines of code necessary to show Eldoc help in the minibuffer.

I don't know if we can implement a meaningful C-h f though, at least not the way it works for Elisp. The problem is that PHP does not let us associate documentation with functions the way we can write docstrings for Elisp, Python, Smalltalk, etc. Actually you can have docstrings for some things in PHP; the existence of utilities like ReflectionClass::getDocComment() and ReflectionFunctionAbstract::getDocComment() prove that. But the support is hit-or-miss, undocumented, and frankly not something I would be confident relying on moving forward. PHP has the technical capability to support doctstrings with functions and variables and everything else, but currently the language does not. And I think we would need that for a version of C-h f that showed more than just a function signature.

Thanks for the ideas guys. Very helpful.

[ejmr]

Also worth consideration is using the php executable itself, e.g. using the output of

$ php --rfunction trim

for generating information on trim(). That approach would still only work for the standard library and not user functions, as far as I know, but is still worth considering.

[ejmr]

I have wanted a similar feature for use with YASnippets, so I started such a project. It uses a PHP program to get information about standard library functions, which may also be useful as one way to get information for Eldoc.

[dhaley]

What about using the already existing doxymacs to tie into eldoc-mode?

http://doxymacs.sourceforge.net/

Doxygen, which is the standard method for generating API documentation for Drupal, can generate xml tag files that look like this:

https://gist.github.com/dhaley/4772491

These tag files list the functions, arguments, and have links to the full doxygen-html-based doco, which is really easy to generate.

I set up doxymacs like this:

https://gist.github.com/dhaley/4773102

Now I can run C-c d ? over a symbol and have my interal doco pop up in a browser.

I don't know about the next step for hooking el-doc into doxymacs, but I wouldn't think it's too hard.

I'm out of time now, but I'll try looking at tying the two together tonight or tomorrow.

[ejmr]

@dhaley

Thank you for the links and suggestion. That does look like a promising approach for implementing Eldoc support for user-defined functions. But since the PHP standard library functions do not have doxygen style commentary I do not think it would work for those. But it is not like we have to choose only one approach. We could use one for standard PHP functions/methods and another for users' code.

[dhaley]

@ejmr

You probably know all this already, but I thought I'd share my findings :-)

For just reading the phpdoc that comes with php, I find Arne Jørgensen's php-extras does the trick with eldoc.

https://github.com/arnested/php-extras.git

It has a function, php-extras-generate-eldoc, that generates a PHP function argument hash table file (mine is 369.7 MB) from php.net see below. So one doesn't have to be on-line for eldoc-documentation-function to have access to the doco - or download anything manually. One can also regenerate the file to get the latest phpdoc using that same function.

Here's the file php-extras produces.

https://gist.github.com/dhaley/4942308

Maybe php-extras can be adapted or merged into php-mode to also work with doxygen generated xml files for users' code.

[ejmr]

Thanks for the extra info @dhaley. At this point I am convinced that the best approach for adding Eldoc support will be a hybrid approach, i.e. using one approach for standard PHP functions and another for the user's own code, and combining those two together.

Regarding php-extras, I would be happy to have all the features it adds in php-mode, not just its Eldoc support. So I'm going to ask Arne Jørgensen about that and see how he feels about merging his work into php-mode.

[arnested]

As I wrote in arnested/php-extras#2 I would be happy to let php-extras be merged into php-mode.

I also believe in some kind of hybrid approach.

In my drupal-mode.el I implemented an attempt at a hybrid approach that would check etags or gtags for function documentation and then fall back to using php-extras table of function documentation if none was found. See drupal-eldoc-documentation-function at https://github.com/arnested/drupal-mode/blob/develop/drupal-mode.el#L461.

In a perfect world eldoc-documentation-function could be a list of functions to try until a match is found.

[ejmr]

Thanks @arnested for the reply regarding php-extras.

The more I think about it, the more I am starting to like the idea of using a prebuilt table of information for standard PHP functions. I started php-auto-yasnippets as a test to explore PHP reflection functionality---and because it would be useful to me personally (heh, says every open-source developer)---and so I want to test out building a table of information about all functions, classes, methods, and extensions possible. Their reflection API makes it possible to get information about all four of those. Right now I don't know how much of it would be useful, but a good start would be to see just how much documentation it is possible to squeeze out of PHP itself.

In a perfect world eldoc-documentation-function could be a list of functions to try until a match is found.

I could not agree more. Regardless of the ways we choose to generate documentation for Eldoc, I believe it will start with eldoc-documentation-function calling a function from php-mode which walks down a list of options, trying each until one of them returns something. Basically what dabbrev does, except for Eldoc.

[dhaley]

I just discovered pman -- man pages for php functions -- and wrote a "describe-function" derived function that might be of interest in the pursuit of making php in emacs more self documenting:

https://gist.github.com/dhaley/7027929

It's a good function to map to C-h f in php-mode.

But I still think merging php-extras into php would be extremely value added for users of this mode. I'm using it now with great success for eldoc purposes.

Maybe if I have time next week I could attempt a pull request of the php-extras merge after talking more with Arne.

[ejmr]

I just discovered pman -- man pages for php functions -- and wrote a "describe-function" derived function that might be of interest in the pursuit of making php in emacs more self documenting:

Thanks for the nice find and example. Using pman looks like a promising way to improve getting function information in PHP Mode. I'm also in agreement about php-extras. I am going to release v1.13 on November 1st but that still gives us two weeks, and I believe we can successfully incorporate some (if not all) of php-extras by then, including support for pman if a user has it available.

[syohex]

There are some implementation of eldoc for php-mode

• https://github.com/sabof/php-eldoc
• https://github.com/zenozeng/php-eldoc

[ejmr]

I wonder if we should consider incorporating the program pman as a fallback to show man-page style information about built-in functions.

[drzraf]

https://github.com/emacs-php/php-mode/pull/551