DocBlockr for Javascript, PHP and CoffeeScript

[spadgos]

I’ve put together a plugin that helps you write docblock style comments.

  /**
   * These things.
   */

Source and extended README is on GitHub.

Features:

• Comments are automatically closed, extended and indented.

• parses the line following the comment to automatically prefill some documentation for you. eg: fills in the @param and @return tags, with tab to jump between sections for quick editing. Makes intelligent guesses about return types of functions, and uses type-hinting and default values (in PHP) to determine parameter data tyeps.

• Double slash comments (// like this) are extended when enter is pressed.

• Variable declarations can be documented, with inferred type information whenever possible.

• Typing an ‘@’ symbol inside a docblock (but only at the start of a line) will bring up a list of all valid jsdoc tags.

• Join lines command (Ctrl/Cmd+J) works nicely in DocBlocks

Version 1 was primarily designed for Javascript (hence the repo name “jsdocs”)
Version 2 now has proper support for PHP and CoffeeScript, and is designed to be able to be extended easily.

Installation is via cloning the repo into your Packages folder, or by using the Package Control plugin (search for “DocBlockr”)

I’d be very happy to hear feedback, feature requests and bug reports.

Repo: github.com/spadgos/sublime-jsdocs
Issues: github.com/spadgos/sublime-jsdocs/issues

Cheers.

[xavi]

Great job!!

Typing @ inside a docblock show all my snippets but no JSDoc supported ones. I’m using Sublime Text 2 build 2131 on Ubuntu Linux

[firefusion]

Awesome! Thank you.

[robin]

Awesome plugin! Really missed this, most of the big IDE’s got this already and now its in sublime to!

Great job !

[spadgos]

[quote=“xavi”]Great job!!

Typing @ inside a docblock show all my snippets but no JSDoc supported ones. I’m using Sublime Text 2 build 2131 on Ubuntu Linux[/quote]

Hey Xavi,

I’m running on Ubuntu as well, but can’t recreate your error. I do have an issue tracker on github if you (or anyone) has any problems. github.com/spadgos/sublime-jsdocs/issues

[spadgos]

Hi all,

I’ve just released an update to the JSDocs package:

From the changelog

[quote]v1.3.0, 5 November 2011
Improvements to handling of single-line comments
Functions beginning with is or has are assumed to return Booleans
Consolidated settings files into Base File.sublime-settings.** If you had configured your settings in jsdocs.sublime-settings, please move them to the Base File settings.**
Setting jsdocs_extend_double_slashes controls whether single-line comments are extended.
Pressing tab in a docblock will tab to match the description block of the previous tag. Use jsdocs_deep_indent to toggle this behaviour.[/quote]

Here’s a demonstration of that last bullet point:

[code]/**

• @param {String} foo Lorem ipsum dolor sit amet
• |<>
  */

– becomes

/**

• @param {String} foo Lorem ipsum dolor sit amet

•                 |
  

*/[/code]

Please do give it a try and let me know if you find any problems or have any feature requests by submitting an issue on the Github tracker: github.com/spadgos/sublime-jsdocs/issues

Cheers!

[spadgos]

Hey guys,

Don’t mean to be spamming, but I’ve released version 2.0.0 of JSDocs which now officially supports PHP. I’ve edited the post at the start of this thread, but the readme on the github repo has the most info.

Give it a try and let me know how it is!

[manu]

Thank you spadgos,

It works well, it’s a real pleasure to not type thousands of ‘*’

[spadgos]

I’ve just released an update, now at version 2.1.0. From the changelog:

• Added a command to join lines inside a docblock which is smart to leading asterisks Press Ctrl+J to join lines
• Variable types are guessed from their name. is and has are assumed to be Booleans, and callback, cb, done, fn and next are assumed to be Functions.
• You can now define your own patterns for mapping a variable name to a type. See the README for documentation about the format
• Autocomplete works better now. @ will also insert the “@” character, allowing you to add any tag you like, even if it isn’t in the autocomplete list.
• Added the full set of PHPDoc tags.

[spadgos]

I thought I’d give this thread a bump since I’ve just added support for CoffeeScript.

[Fannon]

Great Plugin!

One suggestion:
If I enter a “one Line comment” like // and I hit enter it will continue to add // to the next line. Most of the time (or always) I have to get rid of those, so they are not too helpful

Usually if I need multiline comments I use /** oder /*. They work fine!

Greets,
Simon

[spadgos]

Hey Fannon,

There is a configuration option for disabling that feature. Just set “jsdocs_extend_double_slash”: false in your Base File.sublime-settings (or Preferences.sublime-settings if you’re on the dev branch). The other option is to press Shift+Enter and it won’t extend the comment.

[Fannon]

Thanks! Exactly what I wanted

[peppy]

Was looking for something exactly like this. It actually does more than I even thought I wanted, too. Thanks so much!

[mpedrummer]

As a feature request - more control over the whitespace, please!

The deep alignment is pretty close, but there’s a few differences from what my company’s code-sniffing will accept, namely that we don’t align the first column with other tags. So, when there’s @param and @return, this plugin’s deep alignment puts two spaces after the @param, but the code sniffer wants just one.

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

Really, this is awesome, though - not a big deal to fix those myself, and much better than typing out the whole thing!

[spadgos]

hey mpedrummer,

I believe that at least some of your requests are already implemented – you just need to set a config variable. The docs are in the readme and all the options are documented at the bottom of that page.

jsdocs_align_tags (String) Whether the words following the tags should align. Possible values are ‘no’, ‘shallow’ and ‘deep’

For backwards compatibility, false is equivalent to ‘no’, true is equivalent to ‘shallow’
‘shallow’ will align only the first words after the tag. eg:

@param {MyCustomClass} myVariable desc1 @return {String} foo desc2 @property {Number} blahblah desc3
‘deep’ will align each component of the tags, eg:

@param {MyCustomClass} myVariable desc1 @return {String} foo desc2 @property {Number} blahblah desc3

I think you’d probably want “jsdocs_align_tags”: false here.

For the spacing between sections, I’ve put that into an issue so I won’t forget about it.

[mpedrummer]

Thanks spagdos!

Unfortunately, all three settings aren’t quite what we need - which may indicate we should change the code-sniffing standard! Deep alignment is closest - we do align columns, but only within the same tag, not across all tags like deep does. Actually, shallow aligns the first column across all tags, too. “No” means I have to manually align all the columns, which really isn’t the end of the world.

I’m going to leave it on “no” for a few days, see what happens there.

Thanks
MPEDrummer

[Grant]

Anyone ventured into adapting this for C++ yet?

[rchl]

Anyone ventured into adapting this for C++ yet?

Is there some adapting needed for C++? I seem to be happy with how it works with C++ here.

EDIT: But it’s probably because I haven’t seen how it detects parameters and stuff in .js, for example. Until now.

[web559]

This is a beautifully done! Thanks, spadgos.

Is it possible to customize what string to begin tab-completion of the docblock with? I would love to be able to use doc or // instead of /**.