Idea & functionality "stolen" from PHPStorm
How it works:
When the trigger key combination is pressed in the editor, the plugin will analyze the next line of your script.
If the line contains a 'function' or 'var' definition it will insert a DocBlock Comment block in the editor. (Plugin can also be configured to insert a simple DocBlock Comment regardless if next line contains a 'function', 'var' or not.)
One of the benefits of "DocBlock Comments", is that it makes it so much easier to compile documentation later using programs like phpDocumentor
Menu-based features:
- Insert Page DocBlock Comment - Inserts a special Page DocBlock Comment just below the scripting tag. (<?php or <script)
Insert DocBlock Comment - Inserts a DocBlock Comment. (Similar to pressing the trigger combination in the editor.)
Process entire document - Loops through the entire document and adds DocBlock Comments for all functions and var statements.
Update function index - Updates the "Function Index" of Page DocBlock Comments, Creating a list of all functions and their corresponding linenumber in the script.
Goto to function from index - Will jump to the line listed in the Function Index if cursor is placed on line in the Function Index.
Example Screencapture video:
Example of a DocBlock Comment inserted by the plugin:
- Code: Select all
/**
* [add description]
*
* @param array $arg1:
* @param object $arg2: (Passed by reference)
* @param [add type] $arg3: (Optional)
*
* @return [add type]
*
* @access public
* @static
*/
public static function test10(array $arg1, someClass &$arg2, $arg3="1,2,3") {
// Function testcase with various argument types
return $arg1;
}
Code fully commented, so it might be useful as reference for other plugin authors.
Installation:
1) Download plugin .ZIP file.
2) Open WeBuilder and select "Plugins -> Manage Plugins" from the menu.
3) Click "Install" and select the .ZIP file you downloaded in step 1.
Usage:
1) Press the trigger key combination in the editor (default is "/**", but can be changed via Plugin options) on an empty line above a 'function' or 'var' line.
Changes:
v1.1
Added support for "define()" function
Fixed missing return values from the AnalyzeEditorLine() function.
Added plugin option to toggle default description on variables on/off.
Added support for inserting Page DocBlock Comments via menu.
Added support for inserting normal DocBlock Comments via menu.
Added plugin option to set Author, Author Email, License URL and Version Number for use in Page DocBlock Comments.
Removed "Show info on plugin menu" from plugin option, as all menuitems is now located in a "DocBlock Comments" submenu.
Improved the help section menu item.
Added menu option to process entire document and insert missing DocBlock Comments.
Added support for "include", "include_once", "require" & "require_once".
Rewrote the cleanup RegEx methods.
Added function for converting JavaScript funtions into a normalized format.
Added autogenerated Function Index. (Template is part of the Page DocBlock Comment)
Improved var/function detection using the new regex
v1.2
Added better support for PHP "class", "interface" and "abstract".
Added auto update of Function Index when saving HTML, JavaScript or PHP files.
Now adds DocBlock start code (<space>*<space>) if inside a DocBlock Comment when pressing enter.
v1.3
Fixed problem with arguments containing quotes. (Thanks to Domdom for reporting this problem.)
Improved the argument detection on PHP functions. This fixed problem where functions where being detected as vars because of spaces between "function" and starting round bracket. Also fixes problem with arguments containing round brackets. (Thanks to Domdom for reporting this problem.)
Fixed the problem with chars disappearing when pressing enter inside a comment block. (Thanks to Domdom for reporting and fixing this problem.)
Added "Goto to function from index" functionality by Domdom.
Added icons for menuitems.
Added function by Domdom for selecting the complete label incl. brackets when doubleclicking the default labels in comments.
v1.31
Rewrote the doubleclick function as there was problems with it selecting too much.
v1.32
Improved the quote removal function. (Fixes problem with multi quotes in arguments)
v1.33
- Problem with PHP7 "return type declarations" fixed. (Thanks to molkenstehler for reporting this problem.)
Feedback appreciated.
(I only use WeBuilder, so I haven't tested if it works in HTMLPad, Rapid CSS or Rapid PHP.)
Big thanks to Aivars for patiently answering all my plugin questions.
Version 1.33 is available at Github: https://github.com/pmk65/wbp-docblockcomments