tobys / pdv

PHP Documentor for VIM - Generates PHP docblocks

PDV - PHP Documentor for VIM - 2

This is version 2 of PDV - PHP Documentor for VIM, your tool of choice for generating PHP doc blocks. It is a complete rewrite of version 1, which contained code written back in 2005 and earlier. As a result, the code is now way more maintainable and you gain exciting new features:

• Templating support through Vmustache
• Integration with UltiSnips to complete your docs directly after generation

Try it out now.

Requirements

Vmustache is a required plugin for PDV to work

Install

You should install PDV through a VIM plugin manager of your choice. I recommend Vundle for that purpose, but others should work, too. With Vundle you need

Bundle 'tobyS/pdv'

in your .vimrc and then run :BundleInstall in a new VIM instance.

Before using PDV you must set the variable pdv_template_dir which points to your templates. After that, you should map one of the following functions to a key of your choice:

pdv#DocumentCurrentLine()

Generates the doc block as you know it from PDV 1, but using the templates from your template directory.

pdv#DocumentWithSnip()

This function requires UltiSnips as a prerequisite. If you have that installed, your templates will be used as snippets and you will be put into the first tab right after the doc block was generated.

My config for PDV looks like this:

let g:pdv_template_dir = $HOME ."/.vim/bundle/pdv/templates_snip"
nnoremap <buffer> <C-p> :call pdv#DocumentWithSnip()<CR>

There are examples for templates (both a non-snip and a snip version) shipped with PDV.

pdv's Issues

Automatically indent parameters

To comply with standards, it would be nice if doc blocks were automatically indented without the need of manually doing so.

E.g have this:

/* Description
*
* @param string  $aString   A short string.
* @param integer $anInteger A number.
* @param Object  $obj       Some kind of object.
*
* @returns mixed.
*/

Instead of what currently is returned:

/* Description
*
* @param string $aString A short string.
* @param integer $anInteger A number.
* @param Object $obj Some kind of object.
*
* @returns mixed.
*/

I apologize if there is a simple mustache function I can add to my templates but I simply have not been able to find any.

Half broken output

Consider the following function:

function get_acf_option($option = '', $location = 'options', $format = true) {

When I use pdv#DocumentCurrentLine() on it, I get the following output:

/**
 * ${1:get_acf_option}
 *
 * @param ${2:string} $option${3}
 * @param ${4:string} $location${5}
 * @param ${6:mixed} $format${7}
 */
function get_acf_option($option = '', $location = 'options', $format = true) {

I'm using Vundle to manage my plugins, and I've installed both vmustache & pdv:

let g:pdv_template_dir = $HOME ."/.vim/bundle/pdv/templates_snip"

Plugin 'tobyS/vmustache'
Plugin 'tobyS/pdv'

map <F6> :call pdv#DocumentCurrentLine()<CR>

While the current output is definitely better than manually typing all that, I have to quite a bit of cleanup afterwards. Am I doing something wrong perhaps?

Instead docblock I get "0"

I tried the pdv plugin (with the integration with UltiSnips), but, when I active the trigger, all I get is "0" instead the docblocks... Because Ctrlp plugin, I'm using this in my .vimrc file:

let g:pdv_template_dir = $HOME ."/.vim/bundle/pdv/templates_snip"
nnoremap <buffer> <C-d> :call pdv#DocumentWithSnip()<CR>

But even calling :call pdv#DocumentWithSnip() without shortcuts, the result is the same.

Any suggestions?

Split screen

Hi,
Thank you for this plugin. I use it a great deal.

Do you know if it is possible to get it to work in the other file when I have vsplit my terminal and opened another file?

Currently, when I go into the other file and press my control key sequence it does nothing.

Thanks

Shouldn't mustache files have the '.mustache' extension?

Vim detects them wrong as 'smarty' templates. yuck 😄

Function PhpDoc() is undefined

I've installed this plugin using Vundle but I'm having a few problems with it. I've mapped the function PhpDoc() to the key combination ctrl-p but every time I try it I get an error saying that the function is undefined. Am I missing something simple in getting this setup?

Thanks in advance for any ideas.

Interface snippet

Hi Toby,
awesome plugin, really.

the one thing i don't get running is - snippets for interface. Neither for interface, nor for interface methods.

and don't you support traits? they are also not running.

best, Vsevolod

does let g:pdv_template_dir accept list of paths?

does let g:pdv_template_dir accept a list of paths?
I'd like to specify more than one template dir

Complains about deprecated UltiSnips_Anon function usage.

When using PDV together with the latest UltiSnips version (7b8641e) as well as the tagged 3.0 release VIM will complain about the usage of a deprecated function. The error message is:

Error detected while processing function pdv#DocumentWithSnip..UltiSnips_Anon:                               
line    1:
Deprecated UltiSnips_Anon called. Please use UltiSnips#Anon.

Error Template

Error detected while processing function pdv#DocumentWithSnip[5]..<SNR>104_GenerateDocu mentation[2]..<SNR>104_ProcessTemplate[1]..vmustache#RenderFile: line 1: E484: Can't open file /Users/lucaslm/.vim/bundle/pdv/template_snip/function.tpl

My Plugins.

filetype off                  " required

" set the runtime path to include Vundle and initialize
set rtp+=~/.vim/bundle/Vundle.vim
call vundle#begin()
" alternatively, pass a path where Vundle should install plugins
"call vundle#begin('~/some/path/here')

" let Vundle manage Vundle, required
Plugin 'VundleVim/Vundle.vim'
Plugin 'tobyS/vmustache' 
Plugin 'tobyS/pdv'
Plugin 'tpope/vim-vinegar'
Plugin 'scrooloose/nerdtree'
Plugin 'ctrlpvim/ctrlp.vim'
Plugin 'rking/ag.vim'
Plugin 'skwp/greplace.vim'
Plugin 'MarcWeber/vim-addon-mw-utils'
Plugin 'tomtom/tlib_vim'
Plugin 'garbas/vim-snipmate'
Plugin 'tpope/vim-surround'
Plugin 'StanAngeloff/php.vim'
Plugin 'arnaud-lb/vim-php-namespace'
Plugin 'ervandew/supertab'
Plugin 'jiangmiao/auto-pairs'
Plugin 'honza/vim-snippets'
Plugin 'Valloric/YouCompleteMe'
Plugin 'pangloss/vim-javascript'
Plugin 'mattn/emmet-vim'
Plugin 'scrooloose/syntastic'
Plugin 'leafgarland/typescript-vim'
Plugin 'burnettk/vim-angular'
Plugin 'SirVer/ultisnips'
" All of your Plugins must be added before the following line
call vundle#end()            " required
filetype plugin indent on    " required

Error

Error detected while processing function pdv#DocumentWithSnip[5]..177_GenerateDocumentation[2]..177_ProcessTemplate:

Include support for array shorthand syntax

PHP 5.4 included support for the array initialize in the format of "[]" instead of "array()"

NeoSnippet/SnipMate compatbility

Would it be possible for Neosnippet/SnipMate compatibility? They both have the same format, and are very popular.

pdv on window

Hi,

I try for my need to extend pdv for python.

I try to run test on window.
So i go to cygwin with babun.

• install babun
• install ansible in babun
• configure ansible
• configure babun
• install virtualbox from exec
• custom vagrantfile for folder share on window

At the moment i can't run ansible configuration from vagrant,
but if i do the same command that generate vagrant in babun shell,
it's OK.

could you write steps in readMe to try unit test ?

@return tag support

Any plan to add @return tag on function template?

Could not detect parse config for ''

Error detected while processing function pdv#DocumentWithSnip..<SNR>48_DetermineParseConfig:                                                                                 
line    6:
E605: Exception not caught: Could not detect parse config for ''

I used

let g:pdv_template_dir = $HOME."/.vim/bundle/pdv/templates_snip"                                                                                                                 
nnoremap <buffer> <C-p> :call pdv#DocumentWithSnip()<CR>

Buffers issues

Hi, I've added the lines in my .vimrc, as in your example:

let g:pdv_template_dir = $HOME ."/.vim/bundle/pdv/templates_snip"
nnoremap :call pdv#DocumentWithSnip()

This works fine in the first buffer opened, but in all the other buffers it does nothing. Any idea why could that be?

Thanks, this work is much appreciated!

Can't get it to work

Sorry for the nondescript issue title. Big fan of version 1 of your utility, and now I would love to try v2.

I'm using Vundle, and to install this I used the following two lines:

Bundle 'tobyS/vmustache'
Bundle 'tobyS/pdv'

Installed it with BundleInstall.

Since I would like to retain the old behavior, I used the following in my .vimrc:

let g:pdv_template_dir = $HOME ."/.vim/bundle/pdv/templates_snip"
nnoremap <buffer> <C-p> :call pdv#DocumentCurrentLine()<CR>

After doing all this though, whenever I hit CTRL-p, vim just moves the cursor up one line. Any idea how I could start debugging this?

phpdoc for file

Hi, how can I add file documentation? any hints on this? thanx

Windows g:pdv_template_dir setting

To get this plugin working in Windows (using Vundle) I had to use the following for the path:

let g:pdv_template_dir = $HOME . "\\.vim\\bundle\\pdv\\templates"

PhpDoc()

Hi,
In the source code I can read the following:

" You can use this script by mapping the function PhpDoc() to any
" key combination. Hit this on the line where the element to document
" resides and the doc block will be created directly above that line.

Where is the PhpDoc() function you are talking about?

For instance the following plugin relies on PDV https://github.com/adoy/vim-php-refactoring-toolbox

<Leader>da will call your documentation plugin (by default Php Documentor for vim https://github.com/tobyS/pdv) for every uncommented classes, methods, functions and properties.

If I perform the following mapping Vim outputs the following message:

PhpDoc() Vim function doesn't exist

What do you suggest?

Thank you for the hard work.

Mustache variables from buffer special dictionary

It'll be really cool if pdv can load a dictionary from buffer and use it for rendering mustache templates.

Example:

" User can set a viewmodel for pdv per-buffer.
" It's optional, so the user decides how and when this is set.
let b:pdv_mustache_viewmodel = {
    'package': 'Foo',
    'author': 'Bar',
    'copyright': 'Baz',
    ...
}

pdv.vim

" pdv
if exists('b:pdv_mustache_helpers')
    " Merge with current viewmodel
    " ...
endif

templates/class.tpl

/**
 * Class: {{name}}
 * @package    {{package}}
 * @author     {{author}}
 * @copyright  {{copyright}}
 * @license    {{license}}
 * @link       {{link}}
 *{{#interfaces}}
 * @see {{name}}{{/interfaces}}{{#parent}}
 * @see {{name}}{{/parent}}{{#abstract}}
 * @abstract{{/abstract}}{{#final}}
 * @final{{/final}}
 */

Some problems with PDV

Hello!
I try to use PDV (lastest build, downloaded about 20-30 mins ago) to comment following class:

<?php
/**
 * Class: MyClass
 *
 * @see stdClass
 */
class MyClass extends stdClass
{
        /**
         * my_var
         *
         * @var int
         */
        private static $my_var = 1;

        /**
         * testing
         *
         * @param string arg1
         */
        public function testing($arg1 = '')
        {
                return 'no!';
        }

        /**
         * testing2
         *
         * @param mixed arg1
         */
        public function testing2($arg1 = true)
        {
                return false;
        }

        /**
         * testing3
         *
         * @param array arg1
         */
        public function testing3($arg1 = array())
        {
                return new stdClass();
        }

        /**
         * protectedTest
         *
         * @param \stdClass arg1
         */
        protected function protectedTest(\stdClass $arg1)
        {
                return 'something';
        }

        /**
         * privateTest
         *
         * @param string arg1
         */
        private function privateTest($arg1 = '')
        {
                echo 'no return';
        }
}

There are following problems found with this test:

1. There is @access param neither for class var no the method was added
2. There is no @static param was added for the class var
3. There is no @return param for any function
4. There is bug with function testing2 - argument for this function is bool, but it was marked in @param as mixed

Sorry, I don't understand VimL at all that's why I didn't added pull request with fixes. I hope, that you will fix this problems.

Best regards, Nikita Kushnir.

Adding a type to an attribute breaks PDV

If I add a typed attribute to a class
class Foo {
protected string $name = '';
}

and use pdv to add a comment to this attribute, I get an error/exception displayed at the bottom of the vim screen:

"Error detected while processing function pdv#DocumentWithSnip[3]..97_DetermineParseConfig:
E605: Exception not caught: Could not detect parse config for ' protected string $name = '';'

I think this happens for other types as well.

On function comments add the return as well

When generation comments of a function with pdv could it also show what the return value is like it does with the @param. So the end result would look something like the following

/**
 * someFunc
 *
 * @param int $x
 * @param int $y
 * @return int $sum
 */