-
Notifications
You must be signed in to change notification settings - Fork 2
/
Copy pathindex.html
476 lines (405 loc) · 24.4 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
<meta name="description" content="SmartComments, tool that allow you to create implicit comments from javascript source code. ">
<meta name="keywords" content="smartcomments, automatically comments, javascript, js, documentation, comments, tools, application, node js, node">
<meta name="title" content="SmartComments">
<meta http-equiv="X-UA-Compatible" content="IE=edge">
<title>SmartComments</title>
<link rel="stylesheet" href="lib/font-awesome/css/font-awesome.min.css">
<link href="lib/bootstrap/css/bootstrap.min.css" rel="stylesheet">
<link href="assets/styles/styles.css" rel="stylesheet">
<link href="assets/styles/codemirror.css" rel="stylesheet">
<link rel="shortcut icon" type="image/x-icon" href="assets/ico/favicon.png" />
</head>
<body>
<header role="banner">
<div class="container">
<div class="navbar-wrapper navbar-fixed-top">
<div class="navbar navbar-green navbar-static-top">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand navbar-font logo" href="index.html">
<img src="assets/images/logo.png" class="img-responsive img-padding" alt="logo">
<span>/* For idlers men */</span>
</a>
</div>
<div class="navbar-collapse collapse pull-right" role="navigation">
<ul class="nav navbar-nav">
<li id="1" class="active jquery">
<a class="home text-center" href="#home">
<i class="fa fa-home img-padding"></i>
<span class="separate"></span>
Home
</a>
</li>
<li id="6" class="jquery">
<a class="news text-center" href="#news">
<i class="fa fa-lightbulb-o img-padding"></i>
<span class="separate"></span>
What's New
</a>
</li>
<li id="3" class="jquery">
<a class="installation text-center" href="#installation">
<i class="fa fa-download img-padding"></i>
<span class="separate"></span>
Installation
</a>
</li>
<li id="4" class="jquery">
<a class="usage text-center" href="#usage">
<i class="fa fa-terminal img-padding"></i>
<span class="separate"></span>
Usage
</a>
</li>
<li id="2" class="jquery">
<a class="features text-center" href="#features">
<i class="fa fa-list img-padding"></i>
<span class="separate"></span>
Features
</a>
</li>
<li id="5" class="jquery">
<a class="about text-center" href="#about">
<i class="fa fa-pencil img-padding"></i>
<span class="separate"></span>
About
</a>
</li>
</ul>
</div>
</div>
<div class="navbar-line"></div>
</div>
</div>
</div>
</header>
<a href="https://github.com/smartcomments/smartcomments" target="_blank"><img class="github-ribbon" style="z-index: 1040; position: fixed; top: 0; right: 0; border: 0;" src="https://camo.githubusercontent.com/a6677b08c955af8400f44c6298f40e7d19cc5b2d/68747470733a2f2f73332e616d617a6f6e6177732e636f6d2f6769746875622f726962626f6e732f666f726b6d655f72696768745f677261795f3664366436642e706e67" alt="Fork me on GitHub" data-canonical-src="https://s3.amazonaws.com/github/ribbons/forkme_right_gray_6d6d6d.png"></a>
<div class="container">
<br>
<div class="row margin-3x">
<section id="home">
<div class="col-lg-6 col-sm-7 col-md-6 text-center">
<div class="bs-callout bs-callout-info">
<p>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 <a href="http://yuilibrary.com/yui/docs">YUIDocs</a>.</p>
<code>
<span>Latest Stable Version: v0.3.0</span>
</code>
</div>
</div>
<div class="col-lg-5 col-lg-offset-1 col-sm-5 col-md-5 col-md-offset-1">
<pre class="pre-console console">
<span>npm install -g smartcomments</span>
<span>smartcomments --generate</span>
</pre>
</div>
</section>
</div>
<div class="row">
<div class="col-sm-12 col-md-12">
<div class="demo">
</div>
</div>
<div class="col-sm-12 col-md-12 margin-1x">
<div class="pull-left checkbox-group"></div>
<button type="button" class="btn btn-info preview">Preview</button>
<button type="button" class="btn btn-info generate pull-right">
Generate comments
<i class="fa fa-file-text-o img-generate"></i>
</button>
<button type="button" class="btn btn-info undo pull-right hidden-xs">
Undo
<i class="fa fa-undo img-generate"></i>
</button>
<button type="button" class="btn btn-info eraser pull-right hidden-xs">
Clean text editor
<i class="fa fa-eraser img-generate"></i>
</button>
</div>
</div>
<section id="news">
<br>
<div class="row">
<div class="col-sm-12 col-md-12">
<div class="section-logo">
<i class="fa fa-lightbulb-o img-padding"></i>
<span class="separate"></span>
What's New
</div>
</div>
<section id="newscontainer">
<div class="col-sm-12 col-md-12">
<p class="row-background">
<strong>Version 0.3.0</strong>
<span class="separate"></span><br>
<span>* Merge previous comments with new generated ones.</span>
<span class="separate"></span>
<span>* Add optional ignoring of private function in comment generation.</span>
</p>
</div>
</section>
</div>
</section>
<section id="installation">
<br>
<div class="row">
<div class="col-sm-12 col-md-12">
<div class="section-logo">
<i class="fa fa-download img-padding"></i>
<span class="separate"></span>
Installation
</div>
</div>
<div class="col-sm-12 col-md-12">
<p class="row-background">
Make sure you have installed <a href="http://nodejs.org">Node.js</a> and then run the follow command in the console.
</p><br>
<pre class="pre-console">
<span>npm install -g smartcomments</span>
</pre><br>
<p class="row-background">
After the installation process have finished you can put the command <b>smartcomments</b> on the console. You will see something like this.
</p><br>
<pre class="pre-console">
<span>dariel@ltsnotebook:~$ smartcomments -h</span>
<span class="separate"></span>
<span>Hello!!!</span>
<span>using [email protected] on [email protected]</span>
<span class="separate"></span>
<span>Command line options:</span>
<span>-h, --help Show this sttuf</span>
<span>-g, --generate [options] Generate comments from your source</span>
<span> [-t, --target] Specifies the target from which to generate</span>
<span> [-c, --config] Custom configuration file path</span>
</pre>
</div>
</div>
</section>
<section id="usage">
<br>
<div class="row">
<div class="col-sm-12 col-md-12">
<div class="section-logo">
<i class="fa fa-terminal img-padding"></i>
<span class="separate"></span>
Usage
</div>
</div>
<div class="col-sm-12 col-md-12">
<p class="row-background">
Move to the folder where the .js files are located for which you want to generate the comments. And put command <b>--generate</b> on the console.
</p><br>
<pre class="pre-console">
<span>dariel@ltsnotebook:~$ cd some_dir </span>
<span>dariel@ltsnotebook:~/some_dir$ smartcomments --generate</span>
</pre>
<p class="row-background">
Under the hood SmartComments:<br><br>
1 - Search in the current directory if you have any custom configuration file. See <a href="#custom_config">custom configuration</a> for more details.<br><br>
2 - Search recursively through the specified folder, all files that match with <b>match_files</b> option, by default search for .js files only. See <a href="#config_options">configuration options</a> for more details.<br><br>
3 - For each file found SmartComments generates the comments associated with the tags specified in the options. See <a href="#supported_tags">supported tags</a> for more details.<br><br>
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 <b>~my_file.js</b>.
</p>
</div>
<div class="col-sm-12 col-md-12">
<p class="row-background">
If you want to especify the directory or file which you want to generate the comments, then using <b>--target</b> option.
</p><br>
<pre class="pre-console">
<span>dariel@ltsnotebook:~$ smartcomments -g --target /some_dir_or_file</span>
</pre>
</div>
<div class="col-sm-12 col-md-12">
<p class="row-background">
If you want to especify the path of your custom configuration file, then using <b>--config</b> option.
</p><br>
<pre class="pre-console">
<span>dariel@ltsnotebook:~$ smartcomments -g --config /some_dir/smartcomments.json</span>
</pre>
</div>
</div>
<section id="custom_config">
<div class="col-sm-12 col-md-12">
<h4>Custom configuration</h4>
<p class="row-background">
If you want to specify your own configuration, create a file with the <b>smartcomments.json</b> 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 <a href="https://github.com/smartcomments/smartcomments/blob/master/config/smartcomments.json">file example here</a>.
</p>
</div>
</section>
<section id="config_options">
<div class="col-sm-12 col-md-12">
<h4>Configuration options</h4>
<p class="row-background">
<b>target:</b> 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.<br><br>
<b>match_files:</b> Regular expression that defines rules for the file names, for example ["^((?!~).)*.(js)$"] match if the file names ends with .js and do not contain ~.<br><br>
<b>backup:</b> Accepts true or false. If true a backup of the files is created before the file is modified.<br><br>
<b>private:</b> Accepts true or false. If true the privated functions are ignored during the comment generation.<br><br>
<b>favor_generated:</b> 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.<br><br>
<b>Template:</b> 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.<br><br>
</p>
</div>
</section>
</section>
<section id="features">
<br>
<div class="row">
<div class="col-sm-12 col-md-12">
<div class="section-logo">
<i class="fa fa-list img-padding"></i>
<span class="separate"></span>
Features
</div>
</div>
<div class="col-sm-12 col-md-12">
<h4>Sublime Text Plugin</h4>
<p class="row-background">
The <a href="https://github.com/smartcomments/sublime-smartcomments">sublime-smartcomments</a> plugin allow you to launch SmartComments from Sublime Text editor.
</p>
</div>
<div class="col-sm-12 col-md-12">
<h4 id="supported_tags">Supported Tags</h4>
<p class="row-background">
Functions<br><br>
 <strong>@method</strong><br>
 Indicates that the block describes a method for the current class.<br>
 <strong>@description</strong><br>
 The method description.<br>
 <strong>@param</strong><br>
 Defines a parameter for an ordinary @method.<br>
 <strong>@return</strong><br>
 Specifies a method's return value.<br><br>
Using custom tags you may add your own tags. See <a href="#custom-tags">Custom Tags</a> feature for more information.
</p>
</div>
<div class="col-sm-12 col-md-12">
<h4 id="custom-tags">Custom Tags</h4>
<p class="row-background">
<strong>Why Custom tags?</strong>
<span class="separate"></span><br>
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.
<span class="separate"></span><br>
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.
<span class="separate"></span><br>
 <strong>YUI</strong> <span class="separate"></span>
 .fire(type, arguments) <span class="separate"></span><br>
 <strong>jQuery</strong> <span class="separate"></span>
 .trigger( eventType, extraParameters )<span class="separate"></span><br>
 <strong>Ext JS 4</strong> <span class="separate"></span>
 .fireEvent( eventName, args )<span class="separate"></span><br>
 <strong>Angular Js</strong> <span class="separate"></span>
 $emit(name, args)<span class="separate"></span><br>
To solve this problem SmartComments allow you to change or add your own custom tags.<span class="separate"></span>
</p>
<p class="row-background">
<strong>What do you need to know for customizing or add tags? </strong><span class="separate"></span><br>
Firstly you might understand how SmartComments work internally<span class="separate"></span><br>
 1. An AST tree compatible with Mozilla Parser AST is generated from source code using<a href="http://esprima.org/"> Esprima</a><span class="separate"></span>
 2. The AST tree is walked and visitor functions are called from each node<span class="separate"></span>
 3. A concrete visitor function implementation is called from every tags<span class="separate"></span>
 4. The new comments is adding to comment list<span class="separate"></span>
 5. The comment list is traversed, and every comment is inserted into the source code at a specified position.<span class="separate"></span><br>
<strong>In the above process involves two important elements.</strong><span class="separate"></span><br>
<strong>Esprima</strong><span class="separate"></span><br>
 <a href="http://esprima.org/"> Esprima</a> 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.
<span class="separate"></span><br>
<strong>esWalker</strong><span class="separate"></span><br>
 <a href="https://github.com/gigaherz/eswalker">esWalker</a> is a tree walker for Parser API-compatible AST Trees such as generated by Esprima. SmartComments uses esWalker for visiting the defined AST nodes.<span class="separate"></span><br>
You should take a look at both projects before starting to create your template.
</p>
<p class="row-background">
<strong>Where you can customize or add tags?</strong><span class="separate"></span><br>
A file with .js extension must be created, and you must update the <b>template</b> option in config file. See <a href="#custom_config">Custom configuration</a><span class="separate"></span><br>
 template: some/route/mytemplate.js <span class="separate"></span><br>
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.
</p>
<p class="row-background">
<strong>How to customize or add tags?</strong><span class="separate"></span><br>
You can see our <a href="https://github.com/smartcomments/smartcomments/blob/master/templates/default.js">default template</a>, and take this as a reference to create your own.<span class="separate"></span>
Two functions must be implemented in a template:<span class="separate"></span><br>
<b>walkFunctions</b><span class="separate"></span><br>
A list of names of nodes visiting functions used in that template should be returned. You can see the complete nodes visiting functions list <a href="https://github.com/gigaherz/eswalker/blob/master/walker.js">here</a>.<span class="separate"></span><br>
<b>tags</b><span class="separate"></span><br>
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.<span class="separate"></span><br>
Every concrete visiting function receive an object whose properties are:<span class="separate"></span>
 node, parent, fieldName, siblings and index. <span class="separate"></span><br>
Inside <b>tags</b> function scope you can use the <b>template_instance</b> object, which allow you to access to user configuration options. And a <b>comments_list</b> array which contain all comments that you can insert in the source code.<span class="separate"></span><br>
A <b>comment</b> object have two properties:<span class="separate"></span><br>
 pos   //start comment position at source code<span class="separate"></span>
 tags   //a list of <b>tag</b> objects<span class="separate"></span><br>
A <b>tag</b> object must have:<span class="separate"></span><br>
 name   //the name of the tag<span class="separate"></span>
 value   //the tag value Example: @method_name<span class="separate"></span><br>
If you want insert a comment in the source code you just have to create a comment object and push it to <b>comment_list</b> array.<span class="separate"></span><br>
</p>
</div>
</div>
</section>
<section id="about">
<br>
<div class="row">
<div class="col-sm-12 col-md-12">
<div class="section-logo">
<i class="fa fa-pencil img-padding"></i>
<span class="separate"></span>
About
</div>
</div>
<div class="col-sm-12 col-md-12">
<p class="row-background">
SmartComments is developed by a community, in which you can work freely.<br><br>
Node.js Developer: <a href="mailto:[email protected]" title="[email protected]"> Dariel N. Vila Plagado</a>,
Front End Site Developer: <a href="mailto:[email protected]" title="[email protected]">Alberto Román</a>,
Front End Site Developer: <a href="mailto:[email protected]" title="[email protected]">Carlos Madrazo Reyes</a>,
Sublime Text Plugin: <a href="mailto:[email protected]" title="[email protected]">Yolier Galán Tassé </a>,
Front End Site Design: <a href="mailto:[email protected]" title="[email protected]">Pedro Hernández Jiménez</a>,
<a href="http://www.lsauer.com/">Lorenz Lo Sauer</a>,
<a href="https://github.com/karelm">Karel Mcgrail</a>.
Thanks a lot to <a href="https://github.com/rick-kilgore">Rich Kilgore</a> for his great contribution.
</p>
</div>
</div>
</section>
<section>
<div class="col-sm-12 col-md-12">
<h4>Aknowledgement</h4>
<p class="row-background">
To Ms. Marisniulkis Lescaille, Ms. Ana Silvia Telleria, Mr. Julio Cañizares, Mr. Ariya Hidayat <a href="http://esprima.org/">Esprima</a>’ creator,
Mr. David Quintana <a href="https://github.com/gigaherz/eswalker">eswalker</a>’ creator, Mr. Caridy Patino, Principal Engineer at Yahoo!, and to all the persons that helped with this project.
</p>
</div>
</section>
<br>
</div>
<script type="text/javascript" src="lib/jquery/jquery.min.js"
></script>
<script type="text/javascript" src="lib/bootstrap/js/bootstrap.min.js"
></script>
<script type="text/javascript" src="lib/smartcomments/lib/underscore.js"
></script>
<script type="text/javascript" src="lib/require/require.js" data-main="lib/smartcomments/app.js"></script>
<script type="text/javascript" src="lib/codemirror/codemirror.js"
></script>
<script type="text/javascript" src="lib/codemirror/javascript.js"
></script>
<script type="text/javascript" src="script/app.js"
></script>
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-44521541-1', 'smartcomments.github.io');
ga('send', 'pageview');
</script>
</body>
</html>