docjs 0.1.5 → 0.2
Sign up to get free protection for your applications and to get access to all the features.
- data/LICENSE.md +11 -14
- data/README.md +27 -18
- data/docjs.gemspec +3 -3
- data/docs/PATTERNS.md +2 -2
- data/docs/guides/CUSTOMIZE.md +125 -28
- data/docs/guides/TRY.md +2 -1
- data/docs/guides/USE.md +139 -89
- data/lib/code_object/base.rb +0 -10
- data/lib/code_object/converter.rb +3 -3
- data/lib/dom/dom.rb +24 -21
- data/lib/dom/no_doc.rb +2 -2
- data/lib/dom/node.rb +25 -26
- data/lib/helper/helper.rb +161 -36
- data/lib/helper/linker.rb +47 -11
- data/lib/parser/comment.rb +9 -8
- data/lib/parser/comment_parser.rb +9 -10
- data/lib/parser/parser.rb +4 -6
- data/lib/processor.rb +1 -1
- data/lib/token/handler.rb +13 -0
- data/lib/token/token.rb +3 -4
- data/templates/generators/api_pages_generator.rb +0 -4
- data/templates/generators/docs_generator.rb +1 -2
- data/templates/resources/css/application.css +92 -17
- data/templates/resources/js/jcore.js +37 -2
- data/templates/resources/scss/_header.scss +4 -5
- data/templates/resources/scss/_helpers.scss +6 -0
- data/templates/resources/scss/_highlighter.scss +5 -8
- data/templates/resources/scss/_tooltip.scss +2 -2
- data/templates/resources/scss/application.scss +6 -4
- data/templates/tokens/tokens.rb +47 -9
- data/templates/types/function.rb +19 -57
- data/templates/types/object.rb +3 -10
- data/templates/types/prototype.rb +1 -1
- data/test/docs/README.md +35 -14
- metadata +3 -7
- data/docs/ARCHITECTURE.md +0 -0
- data/docs/CONCEPT.md +0 -80
- data/docs/DOCUMENTATION.md +0 -39
- data/templates/views/index.html.erb +0 -0
data/LICENSE.md
CHANGED
@@ -1,19 +1,16 @@
|
|
1
1
|
Copyright (C) 2011 by Jonathan Brachthäuser (http://b-studios.de)
|
2
2
|
|
3
|
-
Permission is hereby granted, free of charge, to any person obtaining a copy
|
4
|
-
|
5
|
-
|
6
|
-
|
7
|
-
copies of the Software, and to permit persons to whom the Software is
|
3
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and
|
4
|
+
associated documentation files (the "Software"), to deal in the Software without restriction,
|
5
|
+
including without limitation the rights to use, copy, modify, merge, publish, distribute,
|
6
|
+
sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is
|
8
7
|
furnished to do so, subject to the following conditions:
|
9
8
|
|
10
|
-
The above copyright notice and this permission notice shall be included in
|
11
|
-
|
9
|
+
The above copyright notice and this permission notice shall be included in all copies or substantial
|
10
|
+
portions of the Software.
|
12
11
|
|
13
|
-
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
14
|
-
|
15
|
-
|
16
|
-
|
17
|
-
|
18
|
-
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
|
19
|
-
THE SOFTWARE.
|
12
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT
|
13
|
+
NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
14
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES
|
15
|
+
OR OTHERLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN
|
16
|
+
CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
CHANGED
@@ -4,51 +4,60 @@ Bad news first: **You still have to write documentation**
|
|
4
4
|
|
5
5
|
Good news: **It will look awesome!!**
|
6
6
|
|
7
|
-
Doc.js is a JavaScript-Documentation tool which detects `tokens` in your comments and
|
8
|
-
|
9
|
-
|
7
|
+
Doc.js is a JavaScript-Documentation tool which detects `tokens` in your comments and generates
|
8
|
+
documentation out of it. Doc.js could be ported pretty easy to any other language, because the most
|
9
|
+
of it's parts are language agnostic.
|
10
|
+
|
11
|
+
Features
|
12
|
+
--------
|
13
|
+
- One command to install
|
14
|
+
- Use markdown in your documentation
|
15
|
+
- Easy to customize (Create your own DSL in a sec!)
|
16
|
+
- Nice and clean default template
|
17
|
+
- Integrates well with your existing deployment
|
18
|
+
- For ruby lovers - it's written in ruby
|
10
19
|
|
11
20
|
Guides
|
12
|
-
|
13
|
-
If you read this, you may belong to one of the following
|
21
|
+
------
|
22
|
+
If you read this, you may belong to one of the following groups:
|
14
23
|
|
15
24
|
1. You want to {file:TRY.md try out Doc.js} for the first time
|
16
25
|
2. You need some more {file:USE.md information, how to use Doc.js}
|
17
26
|
3. You want to {file:CUSTOMIZE.md customize Doc.js}, to exactly fit your needs
|
18
|
-
4. You are interested in the {file:ARCHITECTURE.md architectural insides} of Doc.js
|
19
27
|
|
20
28
|
Supported Ruby-Version
|
21
|
-
|
22
|
-
Currently **only ruby > 1.9.x is supported**. Support for 1.8.x is not planned,
|
23
|
-
|
29
|
+
----------------------
|
30
|
+
Currently **only ruby > 1.9.x is supported**. Support for 1.8.x is not planned, because there are
|
31
|
+
some problems:
|
24
32
|
|
25
33
|
- UTF-8 Support in parser
|
26
34
|
- Intensive use of require_relative
|
27
35
|
- Named captures in RegularExpressions
|
28
36
|
|
29
|
-
For the last two, a rewrite could solve the compatibility issues. Sadly enough
|
30
|
-
|
31
|
-
|
32
|
-
|
37
|
+
For the last two, a rewrite could solve the compatibility issues. Sadly enough currently i don't
|
38
|
+
find the time to fix thoses and the first problem in 1.8.x so only 1.9+ is supported. If you have
|
39
|
+
the time to work on 1.8 compatibility you would make me (and possibly some other 1.8 users) very
|
40
|
+
happy.
|
33
41
|
|
34
42
|
|
35
43
|
Installation
|
36
|
-
|
44
|
+
------------
|
37
45
|
gem install docjs
|
38
46
|
|
39
47
|
Dependencies
|
40
|
-
|
41
|
-
The following Gems are required to make docjs work and should automatically be
|
42
|
-
|
48
|
+
------------
|
49
|
+
The following Gems are required to make docjs work and should automatically be installed while
|
50
|
+
installing docjs:
|
43
51
|
|
44
52
|
- thor
|
45
53
|
- rdiscount
|
46
54
|
|
47
55
|
|
48
56
|
Legal Notice & Contact
|
49
|
-
|
57
|
+
----------------------
|
50
58
|
docjs is released under MIT-License. See LICENSE.md for more information.
|
51
59
|
The used icons, are part of the legendary [famfamfam-silk-iconset](http://www.famfamfam.com/lab/icons/silk/).
|
60
|
+
The font used in title and headlines is a Google-Webfont called `TerminalDosis-Light`.
|
52
61
|
|
53
62
|
For further information about contacting me, please visit my personal [blog](http://b-studios.de).
|
54
63
|
Of course you are also invited to [follow me on twitter](http://twitter.com/#!/__protected).
|
data/docjs.gemspec
CHANGED
@@ -4,10 +4,10 @@ Gem::Specification.new do |s|
|
|
4
4
|
|
5
5
|
|
6
6
|
s.name = 'docjs'
|
7
|
-
s.version = '0.
|
8
|
-
s.date = '2011-06-
|
7
|
+
s.version = '0.2'
|
8
|
+
s.date = '2011-06-28'
|
9
9
|
s.summary = "Javascript Documentation Generator"
|
10
|
-
s.description = "Create
|
10
|
+
s.description = "Create beautiful Javascript documentations with this ruby-gem. It's pretty easy to customize and add your own tokens/DSL."
|
11
11
|
s.homepage = "https://github.com/b-studios/doc.js"
|
12
12
|
s.authors = ["Jonathan Brachthäuser"]
|
13
13
|
s.email = "jonathan@b-studios.de"
|
data/docs/PATTERNS.md
CHANGED
@@ -97,5 +97,5 @@ reveal only the public ones. This can be documented like the following:
|
|
97
97
|
|
98
98
|
}
|
99
99
|
|
100
|
-
Ommiting the comment of the private function `eatPizza` would exclude it from the documentation.
|
101
|
-
may be the disired way of documenting for example a API-Documentation.
|
100
|
+
Ommiting the comment of the private function `eatPizza` would exclude it from the documentation.
|
101
|
+
This may be the disired way of documenting for example a API-Documentation.
|
data/docs/guides/CUSTOMIZE.md
CHANGED
@@ -1,27 +1,3 @@
|
|
1
|
-
Areas
|
2
|
-
=====
|
3
|
-
To visually group the tokens you can specify an area. All tokens for one area (`:sidebar` in this
|
4
|
-
example) will be collected and can be rendered in the view-templates with the
|
5
|
-
{Helper::Helper#render_tokens render_tokens} helper-method.
|
6
|
-
|
7
|
-
render_tokens :of => @code_object, :in => :sidebar
|
8
|
-
|
9
|
-
While {Token::Handler.register registering a new token} you can use any symbol for `area`. But your tokens may not appear in
|
10
|
-
the rendered html-documentation, unless you explicitly call `render_tokens` for each area.
|
11
|
-
|
12
|
-
The default-templates make use of the following areas:
|
13
|
-
|
14
|
-
- :notification
|
15
|
-
- :body
|
16
|
-
- :sidebar
|
17
|
-
- :footnote
|
18
|
-
|
19
|
-
If you don't want your token to be rendered at all, you can use `:none` as value for `area`.
|
20
|
-
|
21
|
-
register :your_token, :area => :none
|
22
|
-
|
23
|
-
|
24
|
-
|
25
1
|
1. Example - Adding a simple token
|
26
2
|
==================================
|
27
3
|
You can extend Doc.js on different levels. The easiest way of customization is to add a simple token.
|
@@ -50,6 +26,8 @@ section (it contains meta-information about the object) we place it there with
|
|
50
26
|
Now our token should be displayed nicely in the sidebar-area on the right side (if you are using the
|
51
27
|
default template).
|
52
28
|
|
29
|
+
You can find more information about areas in {Helper::Helper#render_tokens the Helper-doc}
|
30
|
+
|
53
31
|
|
54
32
|
Using another tokenhandler
|
55
33
|
--------------------------
|
@@ -151,8 +129,127 @@ token-handler.
|
|
151
129
|
|
152
130
|
3. Example - Creating the custom type `class`
|
153
131
|
=============================================
|
154
|
-
If you want to create your own Domain specific language (DSL) it's often not enough to add new
|
155
|
-
and manipulate the templates. Sometimes you need to create your own custom types of objects.
|
156
|
-
example maybe you could need classes, packages or mixins. So in this example we will create a
|
157
|
-
called `class`.
|
132
|
+
If you want to create your own Domain specific language (DSL) it's often not enough to add new
|
133
|
+
tokens and manipulate the templates. Sometimes you need to create your own custom types of objects.
|
134
|
+
For example maybe you could need classes, packages or mixins. So in this example we will create a
|
135
|
+
type called `class`.
|
136
|
+
|
137
|
+
The template-folder `types/` contains 3 items by default:
|
138
|
+
|
139
|
+
types/
|
140
|
+
function.rb
|
141
|
+
object.rb
|
142
|
+
prototype.rb
|
143
|
+
|
144
|
+
We will create a fourth one and call it `class.rb`, which at first only consists of
|
145
|
+
|
146
|
+
class CodeObject::Class < CodeObject::Base
|
147
|
+
end
|
148
|
+
|
149
|
+
Then we need to `require` it from `application.rb`
|
150
|
+
|
151
|
+
require_relative 'types/class.rb'
|
152
|
+
|
153
|
+
We get serious problems here, because in ruby we cannot redefine `Class` without getting into
|
154
|
+
troubles. With nearly all other Type-Names everything wents fine, but for `Class` we need something
|
155
|
+
different. Maybe we can simply call it `Klass` or `ClassType` to bypass any trouble. It's up to you.
|
156
|
+
|
157
|
+
class CodeObject::Klass < CodeObject::Base
|
158
|
+
end
|
159
|
+
|
160
|
+
Based on the name you choosed, we now have to register our token, to be a Type-Creating Token.
|
161
|
+
Every Comment needs exactly one of these type-specificating tokens. With the following line (either
|
162
|
+
in `tokens.rb` or in `class.rb`, after defining our type) we make our token work:
|
163
|
+
|
164
|
+
Token::Handler.register :class, :type => CodeObject::Klass
|
165
|
+
|
166
|
+
Using `@class` in a comment will create an instance of CodeObject::Klass and fill it with all
|
167
|
+
details of that comment.
|
168
|
+
|
169
|
+
If we don't want our type-token to appear in any token-listing like :body or :sidebar we can
|
170
|
+
specify :none for the rendering-area.
|
171
|
+
|
172
|
+
Token::Handler.register :class, :type => CodeObject::Klass, :area => :none
|
173
|
+
|
174
|
+
If we test our customized template with something like
|
175
|
+
|
176
|
+
/**
|
177
|
+
* @class Collection
|
178
|
+
*/
|
179
|
+
var Collection = function() { ... };
|
180
|
+
Collection.prototype = Array.prototype;
|
181
|
+
|
182
|
+
we may notice, that nothing is really different from using `@object` instead. That's only because
|
183
|
+
our template is not yet specialised to work with classes.
|
184
|
+
|
185
|
+
Modifying a Generator
|
186
|
+
---------------------
|
187
|
+
We learned how to create our own templates. But now we need to switch between different templates
|
188
|
+
before rendering starts. To understand where rendering starts, we need to inspect the generators.
|
189
|
+
{Generator::Generator Generators} in Doc.js are pretty much like `Controllers` in Rails. They
|
190
|
+
decide which template to use and where to save the result. So let's take a look at the
|
191
|
+
{Generator::ApiPagesGenerator generators/api_pages_generator.rb}. We can see that every generator
|
192
|
+
is able to choose which layout it want's to render the pages in.
|
193
|
+
|
194
|
+
We may notice, that the ApiPagesGenerator is nothing more than a switch for CodeObject-Types. By
|
195
|
+
default it only differs between {CodeObject::Function functions} and those, that are not functions.
|
196
|
+
|
197
|
+
We can add some code, to use own templates for classes.
|
198
|
+
|
199
|
+
Dom.root.each_child do |node|
|
200
|
+
next if node.is_a? Dom::NoDoc
|
201
|
+
|
202
|
+
if node.is_a? CodeObject::Function
|
203
|
+
render_function node
|
204
|
+
elsif node.is_a? CodeObject::Klass
|
205
|
+
render_class node
|
206
|
+
else
|
207
|
+
render_object node
|
208
|
+
end
|
209
|
+
end
|
210
|
+
|
211
|
+
We invoke a method, which is not yet defined '`render_class`'. This method get's the node as the
|
212
|
+
only parameter and needs to create html-output from it.
|
213
|
+
|
214
|
+
def render_class(code_object)
|
215
|
+
|
216
|
+
Logger.info "Rendering Class: '#{code_object.name}'"
|
217
|
+
|
218
|
+
# This is needed to eventually resolve relative links included in the documentation
|
219
|
+
in_context code_object do
|
220
|
+
|
221
|
+
# The instance-variables are also available in the template-views
|
222
|
+
@class = code_object
|
223
|
+
@methods = @object.children.values.select {|c| c.is_a? CodeObject::Function }
|
224
|
+
|
225
|
+
# Here we call our new template, stored under `views/class/index.html.erb`
|
226
|
+
render 'class/index', :to_file => path_to(code_object, :format => :html)
|
227
|
+
end
|
228
|
+
end
|
229
|
+
|
230
|
+
The last thing (and granted, this may be the biggest part) is to create a template, which is
|
231
|
+
optimzed regarding our new type `class`.
|
158
232
|
|
233
|
+
Combination with a custom handler
|
234
|
+
---------------------------------
|
235
|
+
Often classes are used in context of the classical inheritance. Once class extends another.
|
236
|
+
So we may add a new token `@extends`, which is a text-only token-handler, maybe with a custom
|
237
|
+
template. (See first example above)
|
238
|
+
|
239
|
+
It would be much more interesting to add a documentation syntax like:
|
240
|
+
|
241
|
+
/**
|
242
|
+
* @class Student < Person
|
243
|
+
*/
|
244
|
+
|
245
|
+
This is way easiert, than it may look like at first glance. We only have to write a custom handler:
|
246
|
+
|
247
|
+
Token::Handler.register :class, :type => CodeObject::Klass, :area => :none do |tokenklass, content|
|
248
|
+
extends = /\s*[^\s]+\s*(?:<\s*([^\s]+))/.match(content)
|
249
|
+
|
250
|
+
self.add_token Token::Token::ExtendsToken.new(:content => extends.captures.first) unless extends.nil?
|
251
|
+
end
|
252
|
+
|
253
|
+
What is this doing? We first match our token-content against a regular expression like `(Word (< Word)?)`
|
254
|
+
the inner word is captured. If this matches we use the second part (after the `<`) to create an
|
255
|
+
`@extends` token.
|
data/docs/guides/TRY.md
CHANGED
@@ -51,7 +51,8 @@ The symbols `@function`, `@param` and `@return` are called **tokens** in Doc.js.
|
|
51
51
|
There are many more by default. To see which one you can use simply type:
|
52
52
|
|
53
53
|
docjs tokens
|
54
|
-
|
54
|
+
|
55
|
+
or simply search in {file:USE.md#Available_Tokens this list}.
|
55
56
|
|
56
57
|
Run the documentation and enjoy!
|
57
58
|
--------------------------------
|
data/docs/guides/USE.md
CHANGED
@@ -64,11 +64,9 @@ default:
|
|
64
64
|
- `@prototype`
|
65
65
|
- (`@constructor`)
|
66
66
|
|
67
|
-
|
68
|
-
|
69
|
-
|
70
|
-
as type, so you can see how to create your own custom-types. More information about the `@prototype`
|
71
|
-
- type can be found in {file:PATTERNS.md#Prototypal_Inheritance the documentation-pattern-list}.
|
67
|
+
Advanced concepts like classes, mixins, pseudoclassical inheritence and so on can easily be added by
|
68
|
+
{file:CUSTOMIZE.md creating your own template} or modifying the existing one. More information about
|
69
|
+
the `@prototype`-type can be found in {file:PATTERNS.md#Prototypal_Inheritance the documentation-pattern-list}.
|
72
70
|
|
73
71
|
Types classify the piece of code, you are documenting - so adding a type is essential and **always
|
74
72
|
required**.
|
@@ -111,7 +109,7 @@ can be rewritten as:
|
|
111
109
|
This only works, because the JavaScript-Parser of Doc.js is working scope-aware. So you always can
|
112
110
|
use the dot-notation if your comment is in the lexical-scope of the parent comment.
|
113
111
|
|
114
|
-
The dot-notation (`.sayHello`) was inspired by file-
|
112
|
+
The dot-notation (`.sayHello`) was inspired by file-systems, where one dot refers to the current
|
115
113
|
directory. It also fit's into the JavaScript context, because the child can be accessed by using
|
116
114
|
the dot.
|
117
115
|
|
@@ -120,67 +118,92 @@ Please note: **If relative naming results in errors you still can use absolute n
|
|
120
118
|
Available Tokens
|
121
119
|
================
|
122
120
|
|
123
|
-
|
124
|
-
|
121
|
+
|
122
|
+
Meta-Information Tokens
|
123
|
+
-----------------------
|
125
124
|
| Handler | Area | Template
|
126
125
|
|:-----------------|:-----------|:-------------
|
127
126
|
| :default | :sidebar | :default
|
128
127
|
|
129
|
-
|
130
|
-
|
131
|
-
|
132
|
-
@author Peter Bar (Editor)
|
133
|
-
|
128
|
+
All meta-information tokens appear, along hierachy and file-information, in the sidebar on the right
|
129
|
+
side. (That area is called `:sidebar`)
|
130
|
+
All contents is parsed as one string and can be accessed via the content-accessor-method:
|
134
131
|
|
135
|
-
|
136
|
-
------------
|
137
|
-
Simply creates a function-type and makes it answer `fun.constructor?` with `true`.
|
132
|
+
code_object.tokens[:author].first.content #=> Jonathan
|
138
133
|
|
134
|
+
### @author #
|
135
|
+
### @public #
|
136
|
+
### @private #
|
137
|
+
### @version #
|
139
138
|
|
140
|
-
@deprecated
|
141
|
-
-----------
|
142
|
-
| Handler | Area | Template
|
143
|
-
|:-----------------|:---------------|:-------------
|
144
|
-
| :default | :notification | :default
|
145
139
|
|
146
|
-
|
147
|
-
|
148
|
-
| Handler
|
149
|
-
|
150
|
-
| :
|
140
|
+
Notification Tokens
|
141
|
+
-------------------
|
142
|
+
| Handler | Area | Template
|
143
|
+
|:-----------------|:--------------|:-------------
|
144
|
+
| :default | :notification | :default
|
145
|
+
The notification tokens are all rendered within the default-template, but can be distinguished with
|
146
|
+
css, because the token is added as class.
|
151
147
|
|
152
|
-
|
153
|
-
|
154
|
-
|
155
|
-
|
156
|
-
|
157
|
-
|
158
|
-
|
159
|
-
|
160
|
-
|
148
|
+
/**
|
149
|
+
* @warn This is a warning
|
150
|
+
* @note Please note this
|
151
|
+
*/
|
152
|
+
|
153
|
+
will result in a markup similar to:
|
154
|
+
|
155
|
+
<section class="warn subsection">
|
156
|
+
<h3>Warn</h3>
|
157
|
+
<ul>
|
158
|
+
<li><p>This is a warning</p></li>
|
159
|
+
</ul>
|
160
|
+
</section>
|
161
|
+
<section class="note subsection">
|
162
|
+
<h3>Note</h3>
|
163
|
+
<ul>
|
164
|
+
<li><p>Please note this</p></li>
|
165
|
+
</ul>
|
166
|
+
</section>
|
167
|
+
|
168
|
+
### @deprecated #
|
169
|
+
### @note #
|
170
|
+
### @todo #
|
171
|
+
### @warn #
|
172
|
+
|
173
|
+
|
174
|
+
Type-Creating Tokens
|
175
|
+
--------------------
|
176
|
+
| Handler | Area | Template
|
177
|
+
|:-----------------|:------|:-------------
|
178
|
+
| :noop | :none | :default
|
179
|
+
|
180
|
+
Using type-tokens like `@object` set's the type of the documented CodeObject to {CodeObject::Object}
|
181
|
+
in this case. No token will be added to the codeobject, because the token-types are registered with
|
182
|
+
:noop as token-handler. See {file:USE.md#Types types} for further information about the types in Doc.js.
|
183
|
+
|
184
|
+
All type-tokens take the first word as path of the described object:
|
161
185
|
|
186
|
+
/**
|
187
|
+
* @function Core.extend
|
188
|
+
*/
|
162
189
|
|
163
|
-
|
164
|
-
|
165
|
-
|
190
|
+
`@function Core.extend` describes the function `extend` in the namespace `Core`.
|
191
|
+
### @constructor #
|
192
|
+
Simply creates a function-type and makes it answer `fun.constructor?` with `true`.
|
166
193
|
|
167
|
-
@
|
168
|
-
|
169
|
-
|
170
|
-
|
171
|
-
| :default | :notification | :default
|
194
|
+
### @function #
|
195
|
+
### @method #
|
196
|
+
### @object #
|
197
|
+
### @prototype #
|
172
198
|
|
173
|
-
@object
|
174
|
-
-------
|
175
|
-
Using @object set's the type of the documented CodeObject to {CodeObject::Object}. No token will be
|
176
|
-
added. See {file:USE.md#Types types} for further information about the types in Doc.js.
|
177
199
|
|
178
|
-
|
179
|
-
|
180
|
-
|
181
|
-
|
182
|
-
|
200
|
+
Function-Specific Tokens
|
201
|
+
-----------------------
|
202
|
+
Of course there are the Function-{file:USE.md#Type-Creating_Tokens Type creating tokens} like
|
203
|
+
`@constructor`, `@function` and `@method`. But there are some more tokens, which are designed to
|
204
|
+
work with functions.
|
183
205
|
|
206
|
+
### @overload #
|
184
207
|
You can use overloads, if your **function requires multiple signatures**.
|
185
208
|
So instead of adding your `@param`'s and `@return`'s directly to the function's documentation you
|
186
209
|
specify overloads like:
|
@@ -206,51 +229,78 @@ specify overloads like:
|
|
206
229
|
Please note, that in line 7 of this example the continuation of @overload is achieved due intending
|
207
230
|
the empty line with some spaces.
|
208
231
|
|
232
|
+
### @param #
|
233
|
+
The @param-token supports two ways of usage. The first one is for default tokens like:
|
234
|
+
|
235
|
+
/**
|
236
|
+
* @param [Foo] barname some description
|
237
|
+
*/
|
209
238
|
|
210
|
-
|
211
|
-
------
|
239
|
+
The second one you can use to describe config-objects, which can be passed as an parameter
|
212
240
|
|
213
|
-
|
214
|
-
|
215
|
-
|
216
|
-
|
217
|
-
|
241
|
+
/**
|
242
|
+
* @param configs
|
243
|
+
* Some configuration Object with following properties:
|
244
|
+
* [String] foo some string
|
245
|
+
* [Bar] bar and another one
|
246
|
+
*/
|
247
|
+
|
248
|
+
### @return #
|
249
|
+
### @throws #
|
218
250
|
|
219
|
-
@prop
|
220
|
-
-----
|
221
251
|
|
222
|
-
|
223
|
-
|
252
|
+
Miscellaneous Tokens
|
253
|
+
----------------------
|
254
|
+
### @event #
|
255
|
+
| Handler | Area | Template
|
256
|
+
|:-------------------------|:--------|:-------------
|
257
|
+
| :named_nested_shorthand | :body | :default
|
224
258
|
|
225
|
-
|
226
|
-
|
227
|
-
|
228
|
-
|:-----------------|:-----------|:-------------
|
229
|
-
| :default | :sidebar | :default
|
259
|
+
Basically the event token was created to document which events an object could fire.
|
260
|
+
Because events often contain data with them, there is the possibility to document the format of this
|
261
|
+
data. (this is why the :named_nested_shorthand-handler is used)
|
230
262
|
|
231
|
-
|
232
|
-
|
263
|
+
/**
|
264
|
+
* @event MyCustomEvent
|
265
|
+
* This event will be triggered, if something special happens. The registered handler will be
|
266
|
+
* called with a data-object
|
267
|
+
* [Object] obj This object
|
268
|
+
* [String] msg Some message attached to this event
|
269
|
+
*/
|
270
|
+
|
271
|
+
### @example #
|
272
|
+
| Handler | Area | Template
|
273
|
+
|:-----------------|:-------|:-------------
|
274
|
+
| :named_multiline | :body | :example
|
233
275
|
|
234
|
-
|
235
|
-
----
|
276
|
+
Examples can be used with and without a title:
|
236
277
|
|
237
|
-
|
238
|
-
|
278
|
+
/**
|
279
|
+
* @example no parameters
|
280
|
+
* person.say_hello();
|
281
|
+
*
|
282
|
+
* @example with parameters
|
283
|
+
* person.say_hello({
|
284
|
+
* be_friendly: true
|
285
|
+
* });
|
286
|
+
*/
|
239
287
|
|
240
|
-
@todo
|
241
|
-
-----
|
242
|
-
| Handler | Area | Template
|
243
|
-
|:-----------------|:---------------|:-------------
|
244
|
-
| :default | :notification | :default
|
245
288
|
|
246
|
-
@
|
247
|
-
|
248
|
-
|
249
|
-
|
250
|
-
|
289
|
+
### @prop #
|
290
|
+
| Handler | Area | Template
|
291
|
+
|:------------------|:--------|:-------------
|
292
|
+
| :typed_with_name | :body | :default
|
293
|
+
Prop-tokens are designed to be used to describe properties of objects, which are not objects
|
294
|
+
themselves.
|
251
295
|
|
252
|
-
|
253
|
-
|
254
|
-
|
255
|
-
|
256
|
-
|
296
|
+
/**
|
297
|
+
* @object parameters
|
298
|
+
* @prop [String] foo
|
299
|
+
* @prop [Number] bar
|
300
|
+
*/
|
301
|
+
var parameters = {
|
302
|
+
foo: "Hello World",
|
303
|
+
bar: 42
|
304
|
+
}
|
305
|
+
|
306
|
+
### @see #
|