spadgos / sublime-jsdocs Goto Github PK

Hello,

Package control install jsdoc plugin into Package/JSDocs so this cannot be like that:
"keys": ["@"], "command": "run_macro_file", "args": {"file": "Packages/DocBlockr/jsdocs-auto-complete.sublime-macro"} also in .sublime-menu.

Found a bug when a comment block's ending */ is proceeded by a tab. In this situation, when you try to hit enter after the */ (to create a new line), it instead duplicates the line, appending it to the end of the line. Something like:

/*
    Awesome comment
*/

Would become:

/*
    Awesome comment
*/  */

If you continue to hit enter, it just duplicates the entire line and appends it to the end:

/*
    Awesome comment
*/  */  */  */

This seems to only happen if tabs or spaces exist on the line, before the ending */. But a tab must be the last character before the */. If you add a non tab or space anywhere on the line, proceeding the */, this bug will not trigger:

/*
    Awesome comment
x   */

Other observations:

• Indentation (or lack of) on any other line of the block has no impact.
• Only encountered on OS X, but haven't tried on any other OS.
• The bug is only triggered when hitting return by itself. Cmd + return, shift + return, alt + return do not trigger.

DocBlockr version: 2012.04.30.04.34.38
OS: OS X 10.7.4
Sublime Version: 2197

You really need completely separate completion files for PHP and JS. PHPDoc never uses brackets around type names, so that'll turn out wrong if using a common list. Also, the common list includes a few completions not used in PHPDoc.

With:

/**
 * FooBar|

pressing enter twice will end up with:

/**
 * FooBar
 *
 * |

with trailing space left in the line that contains a 'star' only. Could plugin clean this up automatically when nothing was entered on a line?

Users should be able to define their own hungarian notation which JSDocs would respect. eg:

{
  jsdocs_hungarian_notation_map: [
    {
      "prefix" : "b",
      "type": "bool"  // built-in type: "bool", "function", "string", "int", "float", "number", etc..
    },
    {
      "regex: "rw.*\\d",  // any arbitrary regex
      "type": "Row"       // any arbitrary type
    }
  ]
}

perhaps also add a language selector to these.

Hey,

I've found a bug with DocBlockr and PHP (or maybe more).

Imagine you've got

protected $var

and you use the plugin.

You've got so:

    /**
     * [$var description]
     * @type [type]
     */
     protected $var

So you add a description and you remove the "@type [type]" line. Impossible to add now a '@' character, because the plugin says "unable to open xxxxx/jsdocs-auto-complete.sublime-macro".

It would be nice if you could add support for CoffeeScript, Java, etc. CoffeeScript should be too hard as their is not much difference between .coffee and .js comments/function syntax.

When the function starts with is, or has, the return type should be prefilled with Boolean

The ReadMe mentions that @method is supported (if I've understood it right), but typing @method within a doc-block seems to not auto-complete (or even be present in the auto-complete list).

Everytime I start Sublime Text, I've got now:

"Package Control: The package specified, JSDocs, is not available."

I've uninstalled JSDocs, DocBlockr, gone to my Package Folder, everything was clean. I installed again DocBlockr, and I've got now this issue.

Situation:

/**
 * @param {Number} foo Description description description description
 * |<<tab>>
 */

Actual:

/**
 * @param {Number} foo Description description description description
 *   |
 */

Expected:

/**
 * @param {Number} foo Description description description description
 *                     |
 */

If a function doesn't explicitly return anything (implicitly returning null) then the @return tag is still added to the docblock. An option to disable this would be useful.

I'm used to expanding everything with Tab.
Can this also work with Tab?
Right now my Sublime expands /** to default
/**
*
*/
on Tab.

I've tried finding Key Bindings for this plugin, but I didn't find any.
Could you hint in the correct direction to search if it's easily configurable, please? :)

This is not an issue, rather a request for implementing a feature.

As I can see from the Python source, there is no functionality about guessing a function's return value (in PHP), other than by checking if function's name stars with get / set / add and so on.

It would be very nice if it would look into the function's body and detect return statements. Then we can make a detection algorithm that would rely on typecasts, variable types and so on. If there are many return statements, it is possible to check if they all relate to the same type and suggest it, otherwise just set the return type to 'mixed' instead of [type].

Here are some suggestions on how to detect return type:

If there is a typecast:
return (type)
...will clearly mean that the return type is the one in the brackets.

If the return is a new object / array:
return array(...) or return new Object(...)
In the first case the type is clearly array and in the second it is the object's name.

If the return is a plain value:
return 1 or return 3.14 or return "some string" or return 'another string' etc.
This is actually already implemented in function guessTypeFromValue.

If the return is a variable:
return $var;
Here is where it gets complex. This is rather advanced / extra guess, so its not that important, but it is not impossible to track-back the variable and check for typecasts, plain value assigns and other (the above checks could be used as well).

I do not know Python, so I cannot tell how to implement all these features, but I know they shouldn't be impossible.
I guess the variable track-back could be rather "slow", so it can be an optional feature?

Anyway, I thought I could suggest some "modifications" that I think would be handy for people extensively using such features (like me).

Thanks!

From the forum:

a newline after the descriptions, but no newline before the @return tag.

In commit ca018cf, the setting was added to Base File, when there already is a jsdocs settings file. These should be consolidated to avoid having multiple places of configuraiton.

It would be sweet if the nice column-aligned docblock layout that the plugin creates when you add a new one was maintained while editing, so you don't have to clean up your formatting afterwards.
I'd also like to see more (or possibly configurable) space between the parameter names and descriptions.

Doc blocks in PHP will respond correctly to carriage returns, but do not populate any parameters.

The doc block is also not closed automatically.

when I start defining a property with @, I'm stuck with the supplied list; I can't easily type @method for example.

A lot of code validators complain about trailing whitespaces at the end of the line. This concerns doc blocks also:

http://imagebin.org/212818

Could there be some kind of mechanism that if

• you add two subsequent new lines in comment block
• if the new line above is empty
• The starting whitespace after * would be trimmed away

It would be nice if plug-in can support just simple comment continuation eg:

// some comment<<enter>>

becomes:

// some comment
// <<cursor>>

same with /* only one *

/*<<enter>>

becomes:

/*
 * <<cursor>>
 */

everything without @ tags support

This is my favorite most useful plugin. I only use it for PHP

I am amazed by what you can do with this.

For me I would really like to be able to do something like this...

/**class[ENTER]

/**
 * @class [description] 
 * @description 
 * @version some version
 * @author  Jason Davis
 * @requires Dependencies
 * @todo [description]
 * @example [description]
 */

So at other time it will work like it does now but when I type class after /** it then uses a template for how I want a Class comment to be.

Would really like to see something like this possibly, thanks for the great plugin

Namely, CSS / Sass / SCSS is what I'm wanting.

While there is acutally a cssdoc spec: http://cssdoc.net/, I don't so much care about that, as it would be nice to just have a base level of functionality you could easily extend to specified contexts.

In Textmate, I would just have a docBlock snippet that I applied to all the contexts I wanted. Best way to do that here?

add syntax highlighting for tags ?

Hi there, first of all kudos for this cool plugin,

I have found a small isuue, I am running latest sublime build on debian linux and when I "@" in a comment, the auto complete window pops up then immediatly closes instead of staying open. Strange. Not 100% sure this is a problem in your plugin or somewhere else in my setup but I can autocomplete any thing else.

keypad_enter not continuing DocBlock.

Works in JS, not in PHP.

Situation:

// foo bar| <Ctrl+J>
// baz quux

Actual:

// foo bar // baz quux

Expected:

// foo bar baz quux

Hello!

I love this plugin but for whatever reason after a fresh install via Package Control (not sure how to check the version number of the build I'm running but I assume it's the latest available) I can get everything working great except for the auto indentation to description blocks.

Here is an example of what happens (inside a JS file):

/**
 *  A Test Description Block
 *  @param {number} num This is just an example of<<enter>>
 *  when the auto indentation does not seem to work.
 */

Instead of what I thought should happen for it to look like this:

/**
 *  A Test Description Block
 *  @param {number} num This is just an example of<<enter>>
 *                      when the auto indentation does not seem to work.
 */

Here are the Sublime options I have changed from their defaults:

{
    "auto_complete_commit_on_tab": true,
    "color_scheme": "Packages/User/Espresso Soda.tmTheme",
    "ensure_newline_at_eof_on_save": true,
    "font_size": 14,
    "highlight_line": true,
    "line_padding_bottom": 1,
    "line_padding_top": 1,
    "shift_tab_unindent": true,
    "trim_trailing_white_space_on_save": true,
    "jsdocs_indentation_spaces": 2
}

I'm happy to start debugging this if you tell me where to look.

Many thanks for a great addon,
J.

I'm starting to use yuidoc to generate docs for my node.js JS code and a number of the tags are not supported (such as @for).

I don't really care these extra tags are autocompleted or anything, but if I current type @for, it gets replaced by @fileOverview .. very annoying :)

Is there anyway to specify custom @tags that are acceptable?

The default datatype of parameters named callback, cb, fn, done, next should be function

Situation:

/**
 *  | foo
 */

Hit Enter. Expected:

/**
 *..
 * |foo
 */

Actual:

/**
 *   foo|
 */

eg:

• variables which begin with opt_.. the description should start with "Optional."
• variables named callback.. the description should read just "callback to execute when finished"

...or something

Situation:

/**
 * Foo<<ctrl+j>>
 * Bar
 */

Actual:

/**
 * Foo * Bar
 */

Expected:

/**
 * Foo Bar
 */

http://tomdoc.org/

It's really annoying when doing something stops tab from jumping to the next field. Add a hotkey to reparse the current docblock to re-enable the fields. This should simply convert everything [in square brackets] to fields.

PHP uses a @var tag, and JS apparently uses @type for the same.

I changed the formatVar function to

    if self.inline:
        out.append("@%s %s${1:%s}%s ${1:[description]}" % (
            self.settings['typeTag'],
            "{" if self.settings['curlyTypes'] else "",
            valType,
            "}" if self.settings['curlyTypes'] else ""
        ))
    else:
        out.append("${1:[%s description]}" % (escape(name)))
        out.append("@%s %s${1:%s}%s" % (
            self.settings['typeTag'],
            "{" if self.settings['curlyTypes'] else "",
            valType,
            "}" if self.settings['curlyTypes'] else ""
        ))

and added approriate settings for typeTag in the language settings.

If you press enter at the starting marker of an existing comment, the block is closed, whereas it should only add a new line and asterisk.

Situation:

/**|<<enter>>
 * foo bar
 */

Actual:

/**
 * |
 */
 * foo bar
 */

Expected:

/**
 * |
 * foo bar
 */

It should have spaces between each info.

For instance:

/**
* Short description
*
* Description
*
* @param type $variable1 description
* @param type $variable2 description
*
* @return type $variable description
*/

For the moment, it's more

/**
* Short description
* Description
* @param type $variable1 description
* @param type $variable2 description
* @return type $variable description
*/

I'm coming from Textmate and I want to trigger a block comment with super+option+\ (instead of typing /**[TAB]

Do you know the easiest way to do this?
Right now ST does start a comment when I do that, but it is just /[CURSOR]/.

Autodoc generation doesn't work, when function is written in this way:

function test(
$param1, $param2)
{}

@return [TAB] give me: @m_returnstatus(conn, identifier)

Currently:

<?php
/**
 * DocBlock...
 */[cursor is here...hit return]
 [and you end up here...( there is a space to the left of the cursor :( )]

So you have to backspace every time to get to the beginning of the line. I know in Textmate you can do option+return and it will bring you to the beginning of line...

Hi, this plugin doesn't work on the first line of a js file.

------------------test.js--------------------

/**<< doesn't work here >>

$('something').function () {
/**<< work here >>
};

/**<< doesn't work here >>

Needs option to control whether comment autocompletion happens for single line comments.

If I don't have jsdocs_return_tag in my User settings, I get "None" instead of "@return".
If I set jsdocs_return_tag, it works.
Seems like a minor typo somewhere. :)

Hey lads,

I've got a problem with the plugin.

When I want to comment class attributes, it gives me

    /**
     * [$name description]
     * @type [type]
     */

For php, it should be

    /**
     * [$name description]
     * @var [type] a data type for a class variable
     */

http://phpdocu.sourceforge.net/howto.php

As it now supports PHP, maybe the project should change its name.

I just discovered this nice plugin so I'm not sure if it's a bug in the plugin or new ST2 (I'm using dev builds) but here it goes.

I type:

/**|

press enter and it's autocompleted to:

/**
 * |
 */

If I press enter now (no matter if I type something or not) then I get:

/**
 *
   |
 */

So the "star" is not being added.