Sublime Text 2及常用插件

DocBlockr is a [Sublime Text 2][sublime] package which makes writing documentation a breeze. DocBlockr supports **Javascript**, **ActionScript**, **CoffeeScript**, **Java**, **C** and **C++**, ## Installation ## ### With Package Control ### If you have the [Package Control][package_control] package installed, you can install DocBlockr from inside Sublime Text itself. Open the Command Palette and select "Package Control: Install Package", then search for DocBlockr and you're done! ### Without Package Control ### Go to your Sublime Text 2 Packages directory and clone the repository using the command below: git clone https://github.com/spadgos/sublime-jsdocs.git DocBlockr Don't forget to keep updating it, though! ### Without Git ### Download the latest version from the [tags page][tags]. Unzip to your Sublime Text Packages folder (you can find this by opening ST2 and selecting `Preferences -> Browse Packages...`). You will need to rename the folder from the default (which will be something like `spadgos-sublime-jsdocs-a4bc2a`) to `DocBlockr`. That's it -- you shouldn't even need to restart ST2. ## Feature requests & bug reports ## You can leave either of these things [here][issues]. Pull requests are welcomed heartily! In this repo, the main development branch is `develop` and the stable 'production' branch is `master`. Please remember to base your branch from `develop` and issue the pull request back to that branch. ## Changelog ## - **v2.9.0**, *1 October 2012* - Adds ObjectiveC and ObjectiveC++ support, thanks to some help from [Robb Böhnke](https://github.com/robb) - Very buggy code, support isn't great but it's better than nothing (hopefully). - Single-line comments inside function definitions are handled - Notation rules are applied to functions, which means they can define a return type by their name, eg: `strFoo` - Notation rules can define arbitrary tags, for example: functions with a prefix of "_" should get the `@private` tag. - Given the above addition, JS functions starting with an underscore are no longer marked as `@private` by default. - **v2.8.2**, *28 September 2012* - When a function is defined across many lines, the parser will find the arguments on extra lines. - **v2.8.1**, *13 September 2012* - Pressing <kbd>tab</kbd> on an empty line will perform a deep indentation instead of moving to the next field - Functions starting with `_` will get a `@private` tag in Javascript (thanks to [Andrew Hanna](https://github.com/percyhanna)) - **v2.8.0**, *26 August 2012* - New feature: <kbd>Alt+Q</kbd> to reformat the description field of a docblock to make it fit nicely within your ruler. - Adds support for C++ (thanks to [Rafał Chłodnicki](https://github.com/rchl)) - Indenting to the description field works in languages which don't require type information in the docblock. Older history can be found in [the history file](https://github.com/spadgos/sublime-jsdocs/blob/master/HISTORY.md). ## Usage ## > Below are some examples of what the package does. The pipe (`|`) indicates where the cursor will be after the action has run. Note that there are no keyboard shortcuts required to trigger these completions - just type as normal and it happens for you! ### Docblock completion ### Pressing **enter** or **tab** after `/**` (or `###*` for Coffee-Script) will yield a new line and will close the comment. /**<<enter>> -- becomes -- /** * | */ Single-asterisk comment blocks behave similarly: /*<<enter> -- becomes -- /* | */ If you press asterisk on the first line, it becomes indented with the line above: /* |<<*>> */ /* *| */ ### Function documentation ### However, if the line directly afterwards contains a function definition, then its name and parameters are parsed and some documentation is automatically added. /**<<enter>> function foobar (baz, quux) { } -- becomes -- /** * [foobar description] * @param {[type]} baz [description] * @param {[type]} quux [description] * @return {[type]} */ function foobar (baz, quux) { } You can then press `tab` to move between the different fields. If you have many arguments, or long variable names, it might be useful to spread your arguments across multiple lines. DocBlockr will handle this situation too: /**<<enter>> function someLongFunctionName( withArguments, across, many, lines ) { -- becomes -- /** * [someLongFunctionName description] * @param {[type]} withArguments [description] * @param {[type]} across [description] * @param {[type]} many [description] * @param {[type]} lines [description] * @return {[type]} [description] */ function someLongFunctionName( withArguments, across, many, lines ) { In PHP, if [type hinting][typehinting] or default values are used, then those types are prefilled as the datatypes. /**|<<enter>> function foo(Array $arr, MyClass $cls, $str = "abc", $i = 0, $b = false) {} /** * [foo description] * @param Array $arr [description] * @param MyClass $cls [description] * @param string $str [description] * @param int $i [description] * @param bool $b [description] * @return [type] */ function foo(Array $arr, MyClass $cls, $str = "abc", $i = 0) {} DocBlockr will try to make an intelligent guess about the return value of the function. - If the function name is or begins with "set" or "add", then no `@return` is inserted. - If the function name is or begins with "is" or "has", then it is assumed to return a `Boolean`. - In Javascript, if the function begins with an uppercase letter then it is assumed that the function is a class definition. No `@return` tag is added. - In Javascript, functions beginning with an underscore are assumed to be private: `@private` is added to these. - In PHP, some of the [magic methods][magicmethods] have their values prefilled: - `__construct`, `__destruct`, `__set`, `__unset`, `__wakeup` have no `@return` tag. - `__sleep` returns an `Array`. - `__toString` returns a `string`. - `__isset` returns a `bool`. In Javascript, functions beginning with an underscore are given a `@private` tag by default. ### Variable documentation ### If the line following your docblock contains a variable declaration, DocBlockr will try to determine the data type of the variable and insert that into the comment. /**<<enter>> foo = 1 -- becomes -- /** * [foo description] * @type {Number} */ foo = 1 If you press `shift+enter` after the opening `/**` then the docblock will be inserted inline. /**<<shift+enter>> bar = new Module(); -- becomes -- /** @type {Module} [bar description] */ bar = new Module(); DocBlockr will also try to determine the type of the variable from its name. Variables starting with `is` or `has` are assumed to be booleans, and `callback`, `cb`, `done`, `fn`, and `next` are assumed to be functions. If you use your own variable naming system (eg: hungarian notation: booleans all start with `b`, arrays start with `arr`), you can define these rules yourself. Modify the `jsdocs_notation_map` setting *(in `Base File.sublime-settings`)* like so: ```javascript { "jsdocs_notation_map": [ { "prefix": "b", // a prefix, matches only if followed by an underscore or A-Z "type": "bool" // translates to "Boolean" in javascript, "bool" in PHP }, { "regex": "tbl_?[Rr]ow", // any arbitrary regex to test against the variable name "type": "TableRow" // you can add your own types } ] } ``` The notation map can also be used to add arbitrary tags, according to your own code conventions. For example, if your convention