SmartComments, It's a tool that allow you to create implicit comments from javascript source code. You can integrate it with javascript documentation generators like YUIDocs.
Latest Stable Version: v0.3.0
npm install -g smartcomments smartcomments --generate
Version 0.3.0
* Merge previous comments with new generated ones.
* Add optional ignoring of private function in comment generation.
Make sure you have installed Node.js and then run the follow command in the console.
npm install -g smartcomments
After the installation process have finished you can put the command smartcomments on the console. You will see something like this.
dariel@ltsnotebook:~$ smartcomments -h Hello!!! using smartcomments@0.3.0 on node@0.10.21 Command line options: -h, --help Show this sttuf -g, --generate [options] Generate comments from your source [-t, --target] Specifies the target from which to generate [-c, --config] Custom configuration file path
Move to the folder where the .js files are located for which you want to generate the comments. And put command --generate on the console.
dariel@ltsnotebook:~$ cd some_dir dariel@ltsnotebook:~/some_dir$ smartcomments --generate
Under the hood SmartComments:
1 - Search in the current directory if you have any custom configuration file. See custom configuration for more details.
2 - Search recursively through the specified folder, all files that match with match_files option, by default search for .js files only. See configuration options for more details.
3 - For each file found SmartComments generates the comments associated with the tags specified in the options. See supported tags for more details.
4 – And finally if you have the backup option enable in the configuration file, SmartComments creates a backup of the files, in case you want to return to the previous state. The backup files look like this ~my_file.js.
If you want to especify the directory or file which you want to generate the comments, then using --target option.
dariel@ltsnotebook:~$ smartcomments -g --target /some_dir_or_file
If you want to especify the path of your custom configuration file, then using --config option.
dariel@ltsnotebook:~$ smartcomments -g --config /some_dir/smartcomments.json
If you want to specify your own configuration, create a file with the smartcomments.json name, in the directory where you want to generate the comments. If the configuration file name it’s different than smartcomments.json, SmartComments won’t load your configuration. You can see a configuration file example here.
target: If it is a directory this option specify that the files within this directory are the ones that SmartComment will generate comments for. If it’s a file SmartComment will generate the comments for this file.
match_files: Regular expression that defines rules for the file names, for example ["^((?!~).)*.(js)$"] match if the file names ends with .js and do not contain ~.
backup: Accepts true or false. If true a backup of the files is created before the file is modified.
private: Accepts true or false. If true the privated functions are ignored during the comment generation.
favor_generated: Accepts true or false. When it's set to true (which is the default), it replaces whatever @return or @returns tag is in the source file with the generated one.
Template: Path of the template that you want to use for the comments generation. In a template, a series of algorithm that allow to generate the comments from an AST with the JavaScript code are defined.
The sublime-smartcomments plugin allow you to launch SmartComments from Sublime Text editor.
Functions
@method
Indicates that the block describes a method for the current class.
@description
The method description.
@param
Defines a parameter for an ordinary @method.
@return
Specifies a method's return value.
Using custom tags you may add your own tags. See Custom Tags feature for more information.
Why Custom tags?
To generate implicit comments you need to have a strong knowledge about the language, framework, or company´s coding style. This is a very important thing when we work with a dynamical languages as JavaScript.
The way to declare classes, fire events, or call functions are some examples of elements that change in every implementation. Below you can see, the diferents ways to fire events in 4 JavaScript frameworks.
YUI
.fire(type, arguments)
jQuery
.trigger( eventType, extraParameters )
Ext JS 4
.fireEvent( eventName, args )
Angular Js
$emit(name, args)
To solve this problem SmartComments allow you to change or add your own custom tags.
What do you need to know for customizing or add tags?
Firstly you might understand how SmartComments work internally
1. An AST tree compatible with Mozilla Parser AST is generated from source code using Esprima
2. The AST tree is walked and visitor functions are called from each node
3. A concrete visitor function implementation is called from every tags
4. The new comments is adding to comment list
5. The comment list is traversed, and every comment is inserted into the source code at a specified position.
In the above process involves two important elements.
Esprima
Esprima is a high performance, standard-compliant ECMAScript parser written in ECMAScript. SmartComments uses Esprima to generate an AST tree compatible with Mozilla Parser AST from javascript code.
esWalker
esWalker is a tree walker for Parser API-compatible AST Trees such as generated by Esprima. SmartComments uses esWalker for visiting the defined AST nodes.
You should take a look at both projects before starting to create your template.
Where you can customize or add tags?
A file with .js extension must be created, and you must update the template option in config file. See Custom configuration
template: some/route/mytemplate.js
After do that SmartComments takes the template created by you for generating the comments. You could use this feature to have multiple templates, which you can use and customize as needed, and to share with community also.
How to customize or add tags?
You can see our default template, and take this as a reference to create your own.
Two functions must be implemented in a template:
walkFunctions
A list of names of nodes visiting functions used in that template should be returned. You can see the complete nodes visiting functions list here.
tags
An object with each tag implementations, must be created and returned. In every tag you can make a concrete implementation of the different functions that need visiting, through which you can obtain the AST node information.
Every concrete visiting function receive an object whose properties are:
node, parent, fieldName, siblings and index.
Inside tags function scope you can use the template_instance object, which allow you to access to user configuration options. And a comments_list array which contain all comments that you can insert in the source code.
A comment object have two properties:
pos //start comment position at source code
tags //a list of tag objects
A tag object must have:
name //the name of the tag
value //the tag value Example: @method_name
If you want insert a comment in the source code you just have to create a comment object and push it to comment_list array.
SmartComments is developed by a community, in which you can work freely.
Node.js Developer: Dariel N. Vila Plagado,
Front End Site Developer: Alberto Román,
Front End Site Developer: Carlos Madrazo Reyes,
Sublime Text Plugin: Yolier Galán Tassé ,
Front End Site Design: Pedro Hernández Jiménez,
Lorenz Lo Sauer,
Karel Mcgrail.
Thanks a lot to Rich Kilgore for his great contribution.