wikunia / brackets-funcdocr

FuncDocr generates JS/PHPDoc annotations for your functions

FuncDocr

A brackets extension to generate JS/PHPDocs for your functions.

Important change!

I would like to use parser to offer better support! At the moment ES6 isn't supported in a good way and everything else are just regular expressions. Sorry I'm still learning :D Unfortunately I didn't find a parser to support PHP yet :/ There are two options now: Just waiting until I find a parser for PHP or use regexes for PHP and a parser for JS. I've several extensions and a lot of other projects and that upgrade will take a lot of time. Therefore it would be great if you can check out the next section ;)

You're rich?

You don't need a second yacht and have some coins to spend? Here I am :)

Current amount: 1.04€

How to Use

• Open a JS or PHP file
• set your cursor on a function declaration
  • function cool(stuff)
• Use the ShortCut Ctrl-Alt-D (Win) or Ctrl-Shift-D (Mac) to start the documentation or /** + Enter

The extension will provide a function documentation:

Natural way: /** + Enter

With shortcut:

[[Description]] will be selected so you can start to type. To jump to the next [[tag]] you can use Tab or jump to the last with Shift-Tab. The indenting updates on a tab jump (live indenting).

You will get hints for the [[Type]] tag.

Have fun and stay tuned!

v0.8.4

• It's possible to disable the autoindent functionality in the settings menu.
• @callback links will be visible as [[Type]] hints.

v0.8.0

You can use several JSDoc options to describe your function and you can dblclick on [[...]] to edit the tags.

v0.7.0

Document your react functions!

v0.6.0

@link tags

Easy way to add @link tags to your docs!

v0.5.3

Default values!

v0.5.0

• It's possible to generate the doc block with /** + Enter. You only need to type /** in the line above the function declaration and use enter to start the documentation.

v0.4.0

• The padding for correct indentation updates on a tab jump

v0.3.0

• It's possible to update a doc block if you add a parameter or delete one (you need to use the shortcut again)

v0.2.0

• You get the tag @returns if the function returns a value
• The [[Type]] is recognized if possible.

brackets-funcdocr's Issues

Functions get squished if there are multiline comments in between.

I have copied some function from another (poorly documented) source and had code that looked like this:

/**
 * This is function a
 * @param   {Number}  b this is b
 * @returns {Boolean} always false
 */
var a = function (b) {
    return false;
};

/*
 * Any Block comment
 */
var c = function (d) {
    return false;
};

When I now use the Ctrl+Alt+D hotkey to add / reformat the JsDoc for function c, the first function and the multiline comment are simply deleted and the extension behaves like the first JsDoc belongs to the second function:

/**
 * This is function a
 * @param   {[[Type]]} d [[Description]]
 * @returns {Boolean}  always false
 */
var c = function (d) {
    return false;
};

Assume [param=true] more often

When a parameter is set to

function doing(param) {
    param = (typeof param !== 'undefined') ? param : true;
}

FuncDocr recognizes it as a default parameter and enters
@param {Boolean} [param=true]
accordingly.

However, when I do the following (which is shorter)

function doing(param) {
    param = (typeof param === 'undefined') || param;
}

FuncDocr just puts out:
@param {[[Type]]} noSelection

TL;DR Recognize param = (typeof param === 'undefined') || param; as a default boolean parameter

FuncDocr preferences always show up at Brackets startup

Hi,

I have recently installed your plugin and noticed a strange behavior:

The FuncDocr preferences modal always pop-up when I launch Brackets. Am I the only one?

I'm running Brackets latest stable (build 1.1.0-15558) on Linux Mint Debian Edition. I had this behavior since FuncDocr v0.8.3 and still have it with v0.8.4.

Please tell me if you need more info about to reproduce it or if I can help finding its cause. 😃

Doesn't work with line-wrapped function arguments.

Works, but too long:

RM.frame = function (name, content, x, y, width, height, xSize, ySize, contentX, contentY) {
...
};

Doesn't work:

RM.frame = function (name, content, x, y, width, height,
xSize, ySize, contentX, contentY) {
...
};

Hotkey combo for Windows doesn't work in sprint 42 experimental build 0.42.0-13957

Assuming all I have to do is drop the cursor into the name of the function and hit Ctrl-Alt-D, I'm not getting any response, even after restarting Brackets. Is this just a problem with the version of Brackets?

PHP array()

The following line does not generate anything

public static function fname($var1, $var2=array())

until changed to:

public static function fname($var1, $var2=array)

which is not valid php syntax.

Show "Annotate" option in Edit menu

I couldn't tell how to annotate until I looked at the Github page. This extension could be made even easier to use if there was a option in the Edit menu with the shortcut key shown.

Mockup:

Cannot get it to make the doc neither with shortcut nor natural way

Hi,

I just installed the extension (Version 1.1.0-15558 on Mac/Yosemite), but cannot get it to work on any file, any function (php of course though), no matter whether it's a method in a class or just a plain function.

Neither "/* + Enter" nor the shortcut (I tried to replace it with another custom one since the original couldn't work) will work. The shortcut doesn't do anything and "/* + Enter" simply writes /** + new line...

Am I doing it wrong, or is there a bug somewhere? What can I send you to help you fix this?

Thanks!

Conflict with TODO by Mikael Jorhult

Todo entries won't display with this installed.

can this support properties too?

I would like to add PHPDoc blocks for my class properties as well as methods.

e.g. in both cases bar is a class property and can define a docblock.

class Foo {
    protected $bar = "";
}

I think the same would apply for JS:

function Foo() {
    this.bar = "";
}

Don't remove existing tags on update

The extension offers a wide range of tags as code hints which I sometimes use.
Unfortunately when I update the JsDoc of a function by using the keyboard shortcut all tags exept for the @param and @returns are removed again.

Javascript static methods

Hi again,

I'm not really sure if it's an issue for this project or it's a Brackets issue (sorry in that case, I'll try posting there)...
I've found that Quick Docs (Cmd+K) doesn't work with static methods:

function NewClassObject() {
}
/**
 * Class method (will work)
 * @param {String} param New parameter
 */
NewClassObject.prototype.newMember = function myFunctionMember(param) {
};

/**
 * Static method (will not work)
 * @param {String} param New parameter
 */
NewClassObject.staticMethod = function myStaticFunction(param) {
};

var newClassObject = new NewClassObject();
newClassObject.newMember("");  // <== Quick docs is working
NewClassObject.staticMethod(""); // <== Quick docs is NOT WORKING


var myObject = {};
/**
 * Object method (will not work)
 * @param {String} param New parameter
 */
myObject.newMember = function myObjectFunction(param) {
};

myObject.newMember(""); // <== Quick docs is NOT WORKING

refresh comments with the shortcut

Hello (Oh nooo ;) )
When you have already generate PHPDoc, take this exemple and you generate this :

<?php
function hello(){
return true;
}
?>

The FuncDocr will generate this :

<?php
/**
 * [[Description]]
 * @return boolean [[Description]]
 */
function hello(){
    return true;
}
?>

But, now, replace "true" with something else, like "$var" and you use shortcut to regenerate PHPDocs.
The PHPDoc is again "return boolean".

<?php
/**
 * [[Description]]
 * @return boolean [[Description]]
 */
function hello(){
    return $var;
}
?>

But if you start by "return $var" and end by "return true", the PHPDoc is correct.
Good luck ;)

Keyboard Shorcut overrides delete line

I suggest to use for example Ctrl-Shift-D (this is the one I'm using)

Shortcut doesn't work on OS X, can't set shortcut either

Ctrl-Alt-D doesn't work on a OS X (Tested with OS X 10.7.5), I can't set it to Command-Alt-D either.

FuncDocr doesn't work if the function is inside an object collection

Thanks for your wonderful extension. I'm using FuncDocr 0.8.10 on Brackets 1.2 under Mac OS X 10.10.2
To make an example, If I write this piece of code:

var person = {

    name: "John",

    sayName: function(foo, bar) {
        console.log("Hi, my name is " + this.name + " and I also do " + foo + bar);
        // do some other things...
    }
}

When I try to document the function sayName it doesn't work. I put the cursor over "sayName: function(foo, bar)" and I write "/**" and press enter but nothing happens.

Thank you again and best regards

Conflict with other language syntax hint extensions?

Hi man,your extension works fine.But my other language syntax hint extensions all stop.eg:brackets-wp-functions-hint,brackets-php-syntax-hint.I want to work with them together...
I tested,without your extension,they work fine.

Named function expressions are not recognized

If you try entering the following code

var x = {
    test: function test(x, y) {
    }
};

then, you will not be able to annotate the function test() automatically (neither keyboard shortcut, nor menu command works). But if you change the function to

var x = {
    test: function (x, y) {
    }
};

then FuncDocr annotation works again.

Could the problem be in one of regular expressions?

Workaround for this issue is to wrap the declaration, so that test: part stays on its own line, then annotation works too.

Setting for auto indent

I would like to have a setting to disable the auto indent.

PhpDoc should be @return, not @returns

When creating the docs for a PHP function or method, the docs will say something like this:

/**
 * [[Description]]
 *
 * @returns String [[Description]]
 */
function foo()
{
    return "Bar";
}

The @returns part should be @return (Linking of user is not intended).

On a note, it should be string, not String

add support for es6 classes

i'm working with es6 and classes look like this:

class TodoStore extends EventEmitter {

  constructor() {
    this._todos = {};
  }

  create(text) {
    var id = Date.now();
    this._todos[id] = {
      id,
      complete: false,
      text
    };
  }

  destroy(id) {
    delete this._todos[id];
  }

}

would it be possible to get a support for these? thanks
link: https://babeljs.io/docs/learn-es6/#classes

Align descriptions

I think it's common to align the descriptions of parameters. For instance:

/**
 * [[Description]]
 * @param {[[Type]]} a [[Description]]
 * @param {[[Type]]} simple [[Description]]
 * @param {[[Type]]} test [[Description]]
 */
function foo(a, simple, test) {
}

Should be

/**
 * [[Description]]
 * @param {[[Type]]} a      [[Description]]
 * @param {[[Type]]} simple [[Description]]
 * @param {[[Type]]} test   [[Description]]
 */
function foo(a, simple, test) {
}

ES6 class/method support

It would be fantastic to have ES6 support for class method delcarations;

class Foo {
    /** jsdocs here... */
    bar() {

    }
}

Use Esprima instead of RegExp for JS functions

At some point we should switch from RegExp to using Esprima, which evaluates the code and creates a syntax tree. This will allow us to determine parameter and return types.

Move "FuncDocr Settings" to View menu

"FuncDocr Settings" somewhat works, in a UX sense, when in the "File" menu. However, it decreases usability, as some users assume that the exit button will be at the bottom of the File menu.

When clicking at the bottom menu entry opens up a settings dialog instead of closing the program, a bad experience is created.

Meanwhile, if the FuncDocr Settings was:

• Further up the "Files" menu list, or
• In the View menu list
  usability would be increased.

Add @lastmodifiedBy @createDate please

I'm new using brackets, and I've installed funcDor cause I really love to document all of my work.
I don't know if this function really exist, but i would like to have those options.

Thanks for reading.
Feedback make us grow :)

Preferences for FuncDocr always showing

Love the extension except the Preferences modal is showing each and every time I start up brackets which is starting to get a little annoying. It seems to save the preferences to the preference file ok, so not sure why it shows on startup each time.

Type tag hints do not show when tab forces scrolling

Not exactly a bug, this falls more into the category of unexpected behaviour.

If you hit Tab to jump to the Type tag on a line that is partially or completely rendered off-screen (thus forcing the document to scroll) the Type hints do not show. This occurs whether there are open panes below the document or whether all panes are closed.

Unsure if there is anything that can be done about this, based on a quick glance at the code I assume this is an issue in Brackets itself.

ui to change default.json

want ui to change default properties

Comments in a function

Hello (again ;) ),
when you are in function, you can't use "/*" to write a comment IF there is another function (defined or not by phpdoc) AND below it AND the comment is before a function, check it :

Function with default parameters (PHP)

Hello,
try to add a default parameters in your function, I have this resullt :

    /**
     * [[Description]]
     * @param  [[Type]] [$config=""] [[Description]]
     * @return [[Type]] [[Description]]
     */
    protected function demo($config=""){

So, if I change Type or Description in phpdoc for this variable and I use shortcut to add phpdoc in this method, my changes are removed.
This bug appear only with default parameters.

PHP - Comma as default value in parameter

When using FuncDocr on:

public function parse_csv ($csv_string, $delimiter = ",", $skip_empty_lines = true, $trim_fields = true)

the following is generated:

/**
 * [[Description]]
 * @param  [[Type]] $csv_string                        [[Description]]
 * @param  [[Type]] [$delimiter = "]                    [[Description]]
 * @param  [[Type]] "                                         [[Description]]
 * @param  [[Type]] [$skip_empty_lines = true] [[Description]]
 * @param  [[Type]] [$trim_fields = true]            [[Description]]
 * @return [[Type]] [[Description]]
 */

It is rarely that a comma is given as a default value, so it isn't an important or annoying bug. However, I am just letting you know it's there.

Kind regards!

Error "Cannot assign..." in Brackets console

I'm seeing the following error in my Brackets console: "Cannot assign Ctrl-Alt-D to funcdocr. It is already assigned to funcdocr"

Windows 7 Enterprise SP1 64-bit
Brackets Release 1.1 build 1.1.0-15558
FuncDoor 0.8.2

New line not recognised from header

When pressing enter from the header it does not recognise it as a new line and automatically create a * for the line.

Before (cursor is at the end of the comment header):

After (enter is pressed):

Uncaught TypeError: Cannot read property '0' of undefined

version: 0.8.13
at /Users/zaggino/Library/Application%20Support/Brackets/extensions/user/funcdocr/main.js:793

Reformat JsDoc in one operation

When I add a JsDoc on a function that has already a malformed or incomplete documentation, the existing one is transformed into the new format. This looks to be one step.
But when I decide to revert that change and use undo, I have to undo twice, because there are two steps pushed on the undo stack:

1. Remove all comments
2. Add the new JsDoc (containing the old parts)

I think it would be more intuitive to have this in one batch.

No support for jsx files

Hi,

With React becoming more and more popular it would be great if you could add support for jsx files. This is a very useful plugin, but unfortunately I can't use it due to this reason

Cannot assign 'Ctrl-Alt-D' error

Hi,

have a look at the following issue, please:

Could you please add your binding if and only if the shortcut isn't already taken?

Best Regards,
rb

not working for some files

sometimes getFunctionCodeTypes returns false at main.js:225:

var codeTypes = getFunctionCodeTypes(editor,position,signature.parameters);

then, false.code === undefined at main.js:235:

signature.parameters = checkParamsOptional(codeTypes.code,signature.parameters);

undefined.substr => Uncaught TypeError: Cannot read property 'substr' of undefined at main.js:1204:

code = code.substr(code.indexOf('{')+1);

Use callback for the types

If I have defined a @callback comment I would like to have it too in the list of the types.

Hinting doesn't work

Type Hint (selecting types from dropdown list) doesn't work as your home page picture

Comments -> full doc

Hello,
Better than words, check this GIF :

If you add "/" before a function, you have the full doc but you have the same reaction if "/" is before more one line.
Thanks ! :)

FuncDocr doesn't work if the function is inside an object collection

Hi
I reopen the issue #37 for the new version 0.8.13.

The documentation isn't generated after /** + Enter.
But if the documentation is already generated, FuncDocr works.

Add type to hints

It's possible to add type 'Function' to the context menu ?

Function prototypes

Is it possible to add the ability to use FuncDocr with object prototype functions? Currently will either duplicate the line above, or no action is performed.

Example:

Example.prototype._parseData = function (data, params) {
    // etc
};

Another common case that doesn't work is when you are declaring functions preceding with this.

Example:

this.ExampleException = function(message) {
    this.name = "ExampleException";
    this.message = message;
}

Lubuntu shortcut

hotkey problem in linux
/** + enter problem

brackets version : 0.45
os : ubuntu

Annotate with @return rather than @returns for the javascript Closure Compile

I am writing my javascript code to be compiled against the Google Closure Compiler. The Closure Compiler is expecting me to annotate my functions' return value with "@return" rather than "@returns" (notice the pluralization). Is there anyway that I can configure this extension to automatically output the singular form rather than having to manually correct it every time?

Freezing Brackets

When I try writing /** then pressing enter the entire Brackets freezes I have to end the task. What is up with that issue guys?

Adding extra jdoc tags

Hello,
When I add extra jsdoc tags, for example @throws {Error} Will throw if something is wrong,
the line sometimes gets indented wrong, so that @throws is aligned with previous annotation description text. It seems it only happen if previous annotation text was wrapped. Is there a way to avoid this behavior?
Right now I'm just manually re-indenting those lines, but it gets annoying pretty soon, so I decided to try and ask here :)

Thanks!

BR, Yuriy

Creating new documentation doesn't work on 0.8.8

Typing in /** and hitting enter or using the shortcut Ctrl+Alt+D no longer creates the jsdoc block.

1. Create a function

   var stuff = function(string) {};

2. Write /** on the line above it

3. Hit enter