Plugin: DocBlock Comments v1.33

Browse, download and discuss plugins for Blumentals code editors

Plugin: DocBlock Comments v1.33

Postby pmk65 » Thu Jun 04, 2015 5:30 pm

An editor plugin for PHP and JavaScript coders, that helps you comment your code.
Idea & functionality "stolen" from PHPStorm :mrgreen:

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. 8)

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. :D

Version 1.33 is available at Github: https://github.com/pmk65/wbp-docblockcomments
Attachments
DocBlock Comments.zip
version 1.32
(27.9 KiB) Downloaded 964 times
Last edited by pmk65 on Tue Nov 15, 2016 5:22 pm, edited 7 times in total.
There are 10 types of people in the world: Those who understand binary and those who don't.
User avatar
pmk65
 
Posts: 678
Joined: Sun Dec 20, 2009 9:58 pm
Location: Copenhagen, Denmark

Re: Plugin: DocBlock Comments v1.2

Postby Domdom » Tue Nov 08, 2016 11:08 pm

I tried your plugin (in RapidPHP). It's a good idea for comment class.
But I noticed abnormalities in functions.
Sometimes considers functions as variables or does not find all the parameters. See examples.

Code: Select all
/**
     * [add description]
     *
     * @var function retournerInfoEvenement ($idEvenement
     *
     * @access public
     */
    public function retournerInfoEvenement ($idEvenement, $filtre = array()) {


Code: Select all
    /**
     * [add description]
     *
     * @param  [add type]   $categoriePrimaire
     * @param  $defaut       (Optional)
     *
     * @return [add type]
     *
     * @access public
     */
    public function construireCategorieSecondaire($categoriePrimaire, $defaut = "", $mode = "liste") {


It's better when the parameters are typed. But it cannot see the last parameter.
Domdom
 
Posts: 19
Joined: Tue Nov 01, 2016 10:12 am

Re: Plugin: DocBlock Comments v1.2

Postby pmk65 » Wed Nov 09, 2016 9:30 pm

Domdom wrote:I tried your plugin (in RapidPHP). It's a good idea for comment class.
But I noticed abnormalities in functions.
Sometimes considers functions as variables or does not find all the parameters. See examples.


Nicely spotted. And your examples gave me a good idea of what went wrong. (I had used numeric values when testing optional parameters, so I never saw that string values posed a problem.)

I have made an update if you want to test it?
There are 10 types of people in the world: Those who understand binary and those who don't.
User avatar
pmk65
 
Posts: 678
Joined: Sun Dec 20, 2009 9:58 pm
Location: Copenhagen, Denmark

Re: Plugin: DocBlock Comments v1.2

Postby Domdom » Thu Nov 10, 2016 10:24 am

Thanks Peter. Yes I want.
How to proceed ?
Download the latest version here? Or go through the RapidPHP module manager ?
Domdom
 
Posts: 19
Joined: Tue Nov 01, 2016 10:12 am

Re: Plugin: DocBlock Comments v1.2

Postby Aivars » Thu Nov 10, 2016 11:36 am

Download it here for now, uninstall the old version and then install from .zip. Let me know if it solves the problem for you (you can simply post in this thread) and I'll update the plugin in repository, too.
Blumentals Software Programmer
User avatar
Aivars
Blumentals Software Developer
 
Posts: 2452
Joined: Thu Aug 22, 2002 1:40 pm
Location: Latvia

Re: Plugin: DocBlock Comments v1.2

Postby Domdom » Thu Nov 10, 2016 12:02 pm

OK thanks. I'm waiting Peter update his zip file here.
Domdom
 
Posts: 19
Joined: Tue Nov 01, 2016 10:12 am

Re: Plugin: DocBlock Comments v1.2

Postby pmk65 » Thu Nov 10, 2016 3:43 pm

Aivars wrote:Download it here for now, uninstall the old version and then install from .zip. Let me know if it solves the problem for you (you can simply post in this thread) and I'll update the plugin in repository, too.


I haven't released the fixed version yet as Im still trying to see if I can create a workaround for the problem not being able to suppress linefeed in keypress handler.

When I release a new version, the version number will be updated.

@Domdom: Check your Personal Mail.
There are 10 types of people in the world: Those who understand binary and those who don't.
User avatar
pmk65
 
Posts: 678
Joined: Sun Dec 20, 2009 9:58 pm
Location: Copenhagen, Denmark

Re: Plugin: DocBlock Comments v1.3

Postby pmk65 » Mon Nov 14, 2016 4:16 pm

New version uploaded.

BIG Thanks to Domdom for bugreports, ideas and new functionality.
There are 10 types of people in the world: Those who understand binary and those who don't.
User avatar
pmk65
 
Posts: 678
Joined: Sun Dec 20, 2009 9:58 pm
Location: Copenhagen, Denmark

Re: Plugin: DocBlock Comments v1.32

Postby IceTater » Sat Jan 20, 2018 10:28 pm

:?: How difficult would it be, to add a context-sensitive right-click menu item to fire the plugin after a block of text is selected?
IceTater
 
Posts: 10
Joined: Sat Nov 29, 2014 1:00 am

Re: Plugin: DocBlock Comments v1.32

Postby pmk65 » Sun Jan 21, 2018 1:03 pm

IceTater wrote::?: How difficult would it be, to add a context-sensitive right-click menu item to fire the plugin after a block of text is selected?


You mean as an alternative to pressing the "/**" key combo in the editor?
Such functionality already exists. It's named "Insert DocBlock Comment"
There are 10 types of people in the world: Those who understand binary and those who don't.
User avatar
pmk65
 
Posts: 678
Joined: Sun Dec 20, 2009 9:58 pm
Location: Copenhagen, Denmark

Re: Plugin: DocBlock Comments v1.32

Postby molkenstehler » Wed Feb 13, 2019 9:01 pm

The Insertion of a doc block for an abstract method don't work. It's just inserting blanks and move the Cursor, but that's all. After an Abstract method it's not possible to insert any doc block.
molkenstehler
 
Posts: 5
Joined: Wed Sep 18, 2013 10:53 pm

Re: Plugin: DocBlock Comments v1.32

Postby pmk65 » Thu Feb 14, 2019 1:20 am

molkenstehler wrote:The Insertion of a doc block for an abstract method don't work. It's just inserting blanks and move the Cursor, but that's all. After an Abstract method it's not possible to insert any doc block.


Post a bug report at https://github.com/pmk65/wbp-docblockcomments including a code example I can use for testing. Then I'll take a look at it.
There are 10 types of people in the world: Those who understand binary and those who don't.
User avatar
pmk65
 
Posts: 678
Joined: Sun Dec 20, 2009 9:58 pm
Location: Copenhagen, Denmark

Re: Plugin: DocBlock Comments v1.32

Postby molkenstehler » Thu Feb 14, 2019 11:14 am

pmk65 wrote:
molkenstehler wrote:The Insertion of a doc block for an abstract method don't work. It's just inserting blanks and move the Cursor, but that's all. After an Abstract method it's not possible to insert any doc block.


Post a bug report at https://github.com/pmk65/wbp-docblockcomments including a code example I can use for testing. Then I'll take a look at it.


Don't have an idea how GitHub works.

Another Problem is, if I'm inserting a Page DocBlock and there's a declare-declaration like for strict_types it wouldn't respect it. The declare command needs to be the first sentence in a file.


Folling the Code example for the abtract Problem.

Code: Select all
<?php

  abstract class FormHandler {
    const FORM_IDENT_NAME = 'formID';
    const FORM_IDENT_VALUE = '';

    public $errors = [];
    public $fields = [];

    public $view = '';

    public function __construct(string $formFilename, string $reportFilename) {

    } // __construct

    protected function run() {

    } // run

    public function identifyForm() {

    } // identifyForm

    abstract public function validate() : bool;  // liefert true zurück, wenn alles in Ordnung ist und false, wenn Fehler vorhanden sind
    abstract public function processData() : bool;

    public function getForm() : string {

    } // getForm

    public function getConfirmation() : string {

    } // getConfirmation

  } // FormHandler

?>
molkenstehler
 
Posts: 5
Joined: Wed Sep 18, 2013 10:53 pm

Re: Plugin: DocBlock Comments v1.32

Postby pmk65 » Thu Feb 14, 2019 3:20 pm

molkenstehler wrote:
pmk65 wrote:
molkenstehler wrote:The Insertion of a doc block for an abstract method don't work. It's just inserting blanks and move the Cursor, but that's all. After an Abstract method it's not possible to insert any doc block.


Post a bug report at https://github.com/pmk65/wbp-docblockcomments including a code example I can use for testing. Then I'll take a look at it.


Don't have an idea how GitHub works.

Posting a bug report at Github is extremely simple. You just post on the issue tracker. https://github.com/pmk65/wbp-docblockcomments/issues
Bugreports posted there have 1st priority, as I check my github daily. (Bugreports here tends to get "lost" among the other messages :D)
Also any new releases or fixes will be released at Github.

Seems like it's not the "abstract" keyword that causes the problem, but the PHP7 "return type declarations", as it also fails on the "getConfirmation()" function in your example.
The plugin looks for "function blahblah() {", so the ":" prevent it from detecting the line as a function. (Fixed in the version at Github)

molkenstehler wrote:Another Problem is, if I'm inserting a Page DocBlock and there's a declare-declaration like for strict_types it wouldn't respect it. The declare command needs to be the first sentence in a file.

The plugin was made before PHP7, so that probably why it doesn't detect that. Again please post a bugreport at Github incl. code examples.
There are 10 types of people in the world: Those who understand binary and those who don't.
User avatar
pmk65
 
Posts: 678
Joined: Sun Dec 20, 2009 9:58 pm
Location: Copenhagen, Denmark

Re: Plugin: DocBlock Comments v1.32

Postby pmk65 » Sun Feb 17, 2019 5:40 pm

Version 1.33 is available at Github: https://github.com/pmk65/wbp-docblockcomments

v1.33
- Problem with PHP7 "return type declarations" fixed. (Thanks to molkenstehler for reporting this problem.)
There are 10 types of people in the world: Those who understand binary and those who don't.
User avatar
pmk65
 
Posts: 678
Joined: Sun Dec 20, 2009 9:58 pm
Location: Copenhagen, Denmark

Next

Return to Plugins for HTMLPad / Rapid CSS / Rapid PHP / WeBuilder

Who is online

Users browsing this forum: No registered users and 3 guests

cron