yard-js 0.1.1
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +7 -0
- data/LICENSE.txt +22 -0
- data/README.md +138 -0
- data/lib/yard-js.rb +30 -0
- data/lib/yard-js/code_objects.rb +8 -0
- data/lib/yard-js/code_objects/event_object.rb +11 -0
- data/lib/yard-js/code_objects/property_object.rb +83 -0
- data/lib/yard-js/core_ext/parsejs.rb +13 -0
- data/lib/yard-js/core_ext/yard.rb +17 -0
- data/lib/yard-js/core_ext/yard/code_objects.rb +45 -0
- data/lib/yard-js/core_ext/yard/registry.rb +29 -0
- data/lib/yard-js/core_ext/yard/tags.rb +48 -0
- data/lib/yard-js/core_ext/yard/templates.rb +116 -0
- data/lib/yard-js/core_ext/yard/yardoc.rb +23 -0
- data/lib/yard-js/handlers.rb +7 -0
- data/lib/yard-js/handlers/base.rb +53 -0
- data/lib/yard-js/handlers/class_handler.rb +43 -0
- data/lib/yard-js/handlers/comment_handler.rb +33 -0
- data/lib/yard-js/handlers/constant_handler.rb +50 -0
- data/lib/yard-js/handlers/instance_method_handler.rb +26 -0
- data/lib/yard-js/handlers/mixin_handler.rb +18 -0
- data/lib/yard-js/handlers/module_handler.rb +33 -0
- data/lib/yard-js/parser.rb +23 -0
- data/lib/yard-js/plugin.rb +23 -0
- data/lib/yard-js/tags.rb +37 -0
- data/lib/yard-js/version.rb +3 -0
- data/templates/default/class/setup.rb +11 -0
- data/templates/default/fulldoc/html/css/highlight.github.css +127 -0
- data/templates/default/fulldoc/html/css/style.css +10 -0
- data/templates/default/fulldoc/html/full_list_property.erb +12 -0
- data/templates/default/fulldoc/html/js/highlight.pack.js +1 -0
- data/templates/default/fulldoc/html/setup.rb +18 -0
- data/templates/default/layout/html/headers.erb +17 -0
- data/templates/default/layout/html/setup.rb +14 -0
- data/templates/default/method_details/setup.rb +13 -0
- data/templates/default/module/html/constructor_summary.erb +9 -0
- data/templates/default/module/html/events_details.erb +8 -0
- data/templates/default/module/html/events_summary.erb +20 -0
- data/templates/default/module/html/inherited_methods.erb +8 -0
- data/templates/default/module/html/inherited_properties.erb +8 -0
- data/templates/default/module/html/item_summary.erb +38 -0
- data/templates/default/module/html/method_summary.erb +11 -0
- data/templates/default/module/html/methods_details.erb +8 -0
- data/templates/default/module/html/properties_details.erb +8 -0
- data/templates/default/module/html/properties_summary.erb +11 -0
- data/templates/default/module/setup.rb +75 -0
- data/templates/default/tags/callback.erb +21 -0
- data/templates/default/tags/setup.rb +24 -0
- data/templates/default/tags/value.erb +6 -0
- data/yard-js.gemspec +15 -0
- metadata +92 -0
checksums.yaml
ADDED
@@ -0,0 +1,7 @@
|
|
1
|
+
---
|
2
|
+
SHA1:
|
3
|
+
metadata.gz: 397d27d635f2aaba7eb2e4d6a4c9e4db57189922
|
4
|
+
data.tar.gz: 5c4715dcbba5a68fb4815e9ea91148437444229e
|
5
|
+
SHA512:
|
6
|
+
metadata.gz: decba19d8c378a1e31dc3aaa8506e87196dd4beaf9e3ce06bcc6c16120bb923e9a4ff34bf161e2d2132c8527bd58d2cb89e6993f5e09b6bfc8fa08f82b0409e1
|
7
|
+
data.tar.gz: e2687e8cfb0fb4ab5878e6b34f11f6ad822eb038d4df56fd2e34b8642517d8585f4b6fdd132d96e1b6b4a99fa9e98ea242280ced26547ee4c847b2833eacaf00
|
data/LICENSE.txt
ADDED
@@ -0,0 +1,22 @@
|
|
1
|
+
Copyright (c) 2007-2013 Loren Segal
|
2
|
+
|
3
|
+
Permission is hereby granted, free of charge, to any person
|
4
|
+
obtaining a copy of this software and associated documentation
|
5
|
+
files (the "Software"), to deal in the Software without
|
6
|
+
restriction, including without limitation the rights to use,
|
7
|
+
copy, modify, merge, publish, distribute, sublicense, and/or sell
|
8
|
+
copies of the Software, and to permit persons to whom the
|
9
|
+
Software is furnished to do so, subject to the following
|
10
|
+
conditions:
|
11
|
+
|
12
|
+
The above copyright notice and this permission notice shall be
|
13
|
+
included in all copies or substantial portions of the Software.
|
14
|
+
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
16
|
+
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
|
17
|
+
OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
18
|
+
NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
|
19
|
+
HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
|
20
|
+
WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
|
21
|
+
FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
|
22
|
+
OTHER DEALINGS IN THE SOFTWARE.
|
data/README.md
ADDED
@@ -0,0 +1,138 @@
|
|
1
|
+
# YARD for JavaScript
|
2
|
+
|
3
|
+
A [YARD](http://yardoc.org) plugin that adds support for documenting
|
4
|
+
JavaScript source files with minimal amount of manual declarations, support
|
5
|
+
for YARD syntax, and templates for displaying HTML documentation.
|
6
|
+
|
7
|
+
The plugin relies on certain conventional syntaxes for declaring classes and
|
8
|
+
mixins. See the "Generating documentation" section below for how to customize
|
9
|
+
this.
|
10
|
+
|
11
|
+
## Documenting with yard-js
|
12
|
+
|
13
|
+
Documenting with `yard-js` should be similar to documenting with YARD.
|
14
|
+
Information on how to document with YARD can be found in YARD's
|
15
|
+
[Getting Started Guide](http://rubydoc.org/docs/yard/file/docs/GettingStarted.md).
|
16
|
+
Just like in Ruby, you will document methods or classes by adding docstrings
|
17
|
+
above the definition. Unlike jsdoc, you do not need to explicitly denote the
|
18
|
+
class name or details, as these will be automatically detected by YARD. For
|
19
|
+
instance, the following File class can be documented like so:
|
20
|
+
|
21
|
+
```js
|
22
|
+
/**
|
23
|
+
* This class represents files on disk.
|
24
|
+
*
|
25
|
+
* @see FileSystem
|
26
|
+
*/
|
27
|
+
inherit(IO, {
|
28
|
+
/**
|
29
|
+
* Opens a new file at the location of `filename`
|
30
|
+
*
|
31
|
+
* @param filename [String] the location on disk of the file to open.
|
32
|
+
* @param access [String] a combination or 'r' and 'w' for access modes.
|
33
|
+
*/
|
34
|
+
constructor: function (filename, access) { ... },
|
35
|
+
|
36
|
+
/**
|
37
|
+
* Reads from the open file
|
38
|
+
*
|
39
|
+
* @param numBytes [number] the number of bytes to read. Leave this
|
40
|
+
* empty to read all remaining data.
|
41
|
+
* @return [Buffer] the data read from disk as a buffer.
|
42
|
+
*/
|
43
|
+
read: function (numBytes) { ... }
|
44
|
+
});
|
45
|
+
```
|
46
|
+
|
47
|
+
All [macros and tags](http://rubydoc.org/docs/yard/file/docs/Tags.md) available
|
48
|
+
in YARD are available in `yard-js`.
|
49
|
+
|
50
|
+
## Requirements
|
51
|
+
|
52
|
+
YARD for JavaScript relies on the following software:
|
53
|
+
|
54
|
+
* [Ruby 1.9.x](http://ruby-lang.org)
|
55
|
+
* [Bundler](http://gembundler.com)
|
56
|
+
* [`yard` RubyGem](http://rubygems.org/gems/yard)
|
57
|
+
* [`parsejs` library](http://rubygems.org/gems/parsejs)
|
58
|
+
|
59
|
+
Note that installing Ruby is not covered in the installation section.
|
60
|
+
|
61
|
+
## Installing
|
62
|
+
|
63
|
+
To install, clone the repository and `bundle install` to install dependencies:
|
64
|
+
|
65
|
+
```sh
|
66
|
+
$ git clone git://github.com/lsegal/yard-js
|
67
|
+
$ cd yard-js
|
68
|
+
$ bundle install
|
69
|
+
```
|
70
|
+
|
71
|
+
## Usage
|
72
|
+
|
73
|
+
To generate documentation for a project, change into the project directory
|
74
|
+
and type:
|
75
|
+
|
76
|
+
```sh
|
77
|
+
$ yard -m markdown -e /path/to/yard-js/lib/yard-js
|
78
|
+
```
|
79
|
+
|
80
|
+
To take advantage of class detection you will also need to customize the
|
81
|
+
expressions used by `yard-js` to find class definitions. These are done through
|
82
|
+
the following command line arguments:
|
83
|
+
|
84
|
+
`--define-class-expr`: The syntax used in your code to define a class. For
|
85
|
+
example, `--define-class-expr inherit` will look for the following statement:
|
86
|
+
|
87
|
+
```js
|
88
|
+
inherit(SuperClass, {
|
89
|
+
// class implementation
|
90
|
+
constructor: function() { /* constructor function */ },
|
91
|
+
foo: function() { /* an instance method */ }
|
92
|
+
});
|
93
|
+
```
|
94
|
+
|
95
|
+
`--update-class-expr`: The syntax used in your code to update the class object
|
96
|
+
itself (also known as class level methods/properties). For example,
|
97
|
+
`--update-class-expr update` will detect the following block as a set of class
|
98
|
+
methods:
|
99
|
+
|
100
|
+
```js
|
101
|
+
update(MyClass, {
|
102
|
+
bar: function() { /* a method only available as MyClass.bar() */ }
|
103
|
+
});
|
104
|
+
```
|
105
|
+
|
106
|
+
`--mixin-module-expr`: The syntax used to detect modules mixed into a class.
|
107
|
+
For example, `--mixin-module-expr mixin` will detect:
|
108
|
+
|
109
|
+
```js
|
110
|
+
mixin(MyClass, SomeMixin);
|
111
|
+
```
|
112
|
+
|
113
|
+
To simplify setting these values, you can add these command line arguments
|
114
|
+
to a `.yardopts` file in the root level of your project, for example:
|
115
|
+
|
116
|
+
--define-class-expr inherit
|
117
|
+
--update-class-expr update
|
118
|
+
--mixin-module-expr mixin
|
119
|
+
|
120
|
+
Note that by default YARD uses RDoc comment formatting. This is overridden in
|
121
|
+
the above example by adding `-m markdown` to use markdown formatting for
|
122
|
+
documentation comments.
|
123
|
+
|
124
|
+
## Known Issues
|
125
|
+
|
126
|
+
1. This plugin is currently not a true "plugin". This will require availability
|
127
|
+
as a RubyGem, which will happen soon.
|
128
|
+
|
129
|
+
2. This plugin is currently not compatible with the YARD server architecture.
|
130
|
+
This is being worked on.
|
131
|
+
|
132
|
+
3. This plugin cannot document Ruby code alongside JavaScript code due to the
|
133
|
+
way it modifies YARD internals. Making yard-js work side-by-side Ruby code
|
134
|
+
will be a long-term goal.
|
135
|
+
|
136
|
+
## License
|
137
|
+
|
138
|
+
`yard-js` is available under the MIT license.
|
data/lib/yard-js.rb
ADDED
@@ -0,0 +1,30 @@
|
|
1
|
+
require 'ostruct'
|
2
|
+
|
3
|
+
module YARDJS
|
4
|
+
class Options
|
5
|
+
%w(define_class_expression
|
6
|
+
update_class_expression
|
7
|
+
mixin_module_expression).each do |name|
|
8
|
+
attr_reader(name)
|
9
|
+
define_method("#{name}=") do |value|
|
10
|
+
instance_variable_set("@#{name}", /\A#{value}\Z/)
|
11
|
+
end
|
12
|
+
end
|
13
|
+
|
14
|
+
def initialize
|
15
|
+
self.define_class_expression ||=
|
16
|
+
ENV['DEFINE_CLASS_EXPR'] || 'inherit'
|
17
|
+
self.update_class_expression ||=
|
18
|
+
ENV['UPDATE_CLASS_EXPR'] || 'update'
|
19
|
+
self.mixin_module_expression ||=
|
20
|
+
ENV['MIXIN_MODULE_EXPR'] || 'mixin'
|
21
|
+
end
|
22
|
+
end
|
23
|
+
|
24
|
+
def self.options
|
25
|
+
@options ||= Options.new
|
26
|
+
end
|
27
|
+
end
|
28
|
+
|
29
|
+
require_relative 'yard-js/plugin'
|
30
|
+
require_relative 'yard-js/version'
|
@@ -0,0 +1,83 @@
|
|
1
|
+
module YARDJS
|
2
|
+
module CodeObjects
|
3
|
+
class PropertyObject < Base
|
4
|
+
attr_accessor :parameters, :property_type
|
5
|
+
|
6
|
+
def aliases; [] end
|
7
|
+
|
8
|
+
# @return whether or not the method is the #initialize constructor method
|
9
|
+
def constructor?
|
10
|
+
name == :constructor && namespace.is_a?(YARD::CodeObjects::ClassObject)
|
11
|
+
end
|
12
|
+
|
13
|
+
def relative_path(other)
|
14
|
+
case other
|
15
|
+
when PropertyObject
|
16
|
+
if other.parent == parent
|
17
|
+
other.name.to_s
|
18
|
+
else
|
19
|
+
other.path
|
20
|
+
end
|
21
|
+
else
|
22
|
+
if parent == other
|
23
|
+
other.name.to_s
|
24
|
+
else
|
25
|
+
other.path
|
26
|
+
end
|
27
|
+
end
|
28
|
+
end
|
29
|
+
|
30
|
+
def scope; :class end
|
31
|
+
def attr_info; nil end
|
32
|
+
|
33
|
+
# @return [Boolean] whether or not this method was created as a module
|
34
|
+
# function
|
35
|
+
# @since 0.8.0
|
36
|
+
def module_function?
|
37
|
+
false
|
38
|
+
end
|
39
|
+
|
40
|
+
# @return [Boolean] whether the method is a writer attribute
|
41
|
+
# @since 0.5.3
|
42
|
+
def writer?
|
43
|
+
true
|
44
|
+
end
|
45
|
+
|
46
|
+
# @return [Boolean] whether the method is a reader attribute
|
47
|
+
# @since 0.5.3
|
48
|
+
def reader?
|
49
|
+
true
|
50
|
+
end
|
51
|
+
|
52
|
+
# Tests if the object is defined as an attribute in the namespace
|
53
|
+
# @return [Boolean] whether the object is an attribute
|
54
|
+
def is_attribute?
|
55
|
+
false
|
56
|
+
end
|
57
|
+
|
58
|
+
# Tests if the object is defined as an alias of another method
|
59
|
+
# @return [Boolean] whether the object is an alias
|
60
|
+
def is_alias?
|
61
|
+
false
|
62
|
+
end
|
63
|
+
|
64
|
+
# Tests boolean {#explicit} value.
|
65
|
+
#
|
66
|
+
# @return [Boolean] whether the method is explicitly defined in source
|
67
|
+
def is_explicit?
|
68
|
+
true
|
69
|
+
end
|
70
|
+
|
71
|
+
# @return [MethodObject] the object that this method overrides
|
72
|
+
# @return [nil] if it does not override a method
|
73
|
+
# @since 0.6.0
|
74
|
+
def overridden_method
|
75
|
+
nil
|
76
|
+
end
|
77
|
+
|
78
|
+
def value
|
79
|
+
tag(:value) ? tag(:value).text : ''
|
80
|
+
end
|
81
|
+
end
|
82
|
+
end
|
83
|
+
end
|
@@ -0,0 +1,13 @@
|
|
1
|
+
$:.unshift(File.expand_path('~/parsejs/lib'))
|
2
|
+
|
3
|
+
require 'parsejs'
|
4
|
+
require 'parsejs/stringifier'
|
5
|
+
|
6
|
+
class ParseJS::AST::Node
|
7
|
+
def line; 0 end
|
8
|
+
def show; ParseJS::Stringifier.to_string(self) end
|
9
|
+
def comments_hash_flag; nil end
|
10
|
+
def comments_range; nil end
|
11
|
+
alias source show
|
12
|
+
attr_accessor :comments
|
13
|
+
end
|
@@ -0,0 +1,17 @@
|
|
1
|
+
require 'yard'
|
2
|
+
|
3
|
+
require_relative 'yard/code_objects'
|
4
|
+
require_relative 'yard/registry'
|
5
|
+
require_relative 'yard/tags'
|
6
|
+
require_relative 'yard/templates'
|
7
|
+
require_relative 'yard/yardoc'
|
8
|
+
|
9
|
+
YARD::CodeObjects::NSEP.replace('.')
|
10
|
+
YARD::CodeObjects.send(:remove_const, :NSEPQ)
|
11
|
+
YARD::CodeObjects::NSEPQ = Regexp.quote(YARD::CodeObjects::NSEP)
|
12
|
+
YARD::CodeObjects::CSEP.replace('.')
|
13
|
+
YARD::CodeObjects.send(:remove_const, :CSEPQ)
|
14
|
+
YARD::CodeObjects::CSEPQ = Regexp.quote(YARD::CodeObjects::CSEP)
|
15
|
+
YARD::CodeObjects::ISEP.replace('.')
|
16
|
+
YARD::CodeObjects.send(:remove_const, :ISEPQ)
|
17
|
+
YARD::CodeObjects::ISEPQ = Regexp.quote(YARD::CodeObjects::ISEP)
|
@@ -0,0 +1,45 @@
|
|
1
|
+
require 'yard'
|
2
|
+
|
3
|
+
module YARD
|
4
|
+
module CodeObjects
|
5
|
+
class Base
|
6
|
+
alias old_relative_path relative_path
|
7
|
+
def relative_path(other)
|
8
|
+
if other.is_a?(NamespaceObject)
|
9
|
+
other.path
|
10
|
+
else
|
11
|
+
old_relative_path(other)
|
12
|
+
end
|
13
|
+
end
|
14
|
+
end
|
15
|
+
|
16
|
+
class NamespaceObject
|
17
|
+
def properties
|
18
|
+
children.select {|o| o.type == :property }
|
19
|
+
end
|
20
|
+
|
21
|
+
def events
|
22
|
+
children.select {|o| o.type == :event }
|
23
|
+
end
|
24
|
+
|
25
|
+
def constants(opts = {})
|
26
|
+
properties.select {|o| o.has_tag?(:constant) }
|
27
|
+
end
|
28
|
+
|
29
|
+
def relative_path(other)
|
30
|
+
if self == other.parent
|
31
|
+
other.name.to_s
|
32
|
+
else
|
33
|
+
other.path
|
34
|
+
end
|
35
|
+
end
|
36
|
+
end
|
37
|
+
|
38
|
+
class ClassObject
|
39
|
+
def initialize(namespace, name, *args, &block)
|
40
|
+
super
|
41
|
+
self.superclass = "Object"
|
42
|
+
end
|
43
|
+
end
|
44
|
+
end
|
45
|
+
end
|
@@ -0,0 +1,29 @@
|
|
1
|
+
module YARD
|
2
|
+
module Registry
|
3
|
+
def self.resolve(namespace, name, inheritance = false, proxy_fallback = false, type = nil)
|
4
|
+
if namespace.is_a?(CodeObjects::Proxy)
|
5
|
+
return proxy_fallback ? CodeObjects::Proxy.new(namespace, name, type) : nil
|
6
|
+
end
|
7
|
+
|
8
|
+
if namespace == :root || !namespace
|
9
|
+
namespace = root
|
10
|
+
else
|
11
|
+
namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject)
|
12
|
+
end
|
13
|
+
orignamespace = namespace
|
14
|
+
|
15
|
+
name = name.to_s.sub(/^\./, '')
|
16
|
+
nss = namespace.path.split('.')
|
17
|
+
nss = [] if nss == ['']
|
18
|
+
while nss.size >= 0
|
19
|
+
if obj = at((nss + [name]).compact.join('.'))
|
20
|
+
return obj
|
21
|
+
end
|
22
|
+
break if nss.size == 0
|
23
|
+
nss.pop
|
24
|
+
end
|
25
|
+
|
26
|
+
proxy_fallback ? CodeObjects::Proxy.new(orignamespace, name, type) : nil
|
27
|
+
end
|
28
|
+
end
|
29
|
+
end
|
@@ -0,0 +1,48 @@
|
|
1
|
+
module YARD
|
2
|
+
module Tags
|
3
|
+
class MethodDirective
|
4
|
+
def method_name
|
5
|
+
sig = sanitized_tag_signature
|
6
|
+
if sig
|
7
|
+
sig[/\A\s*([^\(; \t]+)/, 1]
|
8
|
+
else
|
9
|
+
handler.call_params.first
|
10
|
+
end
|
11
|
+
end
|
12
|
+
|
13
|
+
def create_object
|
14
|
+
name = method_name
|
15
|
+
visibility = parser.state.visibility || handler.visibility
|
16
|
+
ns = CodeObjects::NamespaceObject === object ? object : handler.namespace
|
17
|
+
obj = YARDJS::CodeObjects::PropertyObject.new(ns, name)
|
18
|
+
handler.register_file_info(obj)
|
19
|
+
handler.register_source(obj)
|
20
|
+
handler.register_visibility(obj, visibility)
|
21
|
+
handler.register_group(obj)
|
22
|
+
obj.signature = method_signature
|
23
|
+
obj.parameters = OverloadTag.new(:overload, method_signature).parameters
|
24
|
+
obj.docstring = Docstring.new!(parser.text, parser.tags, obj,
|
25
|
+
parser.raw_text)
|
26
|
+
obj.property_type = :function
|
27
|
+
handler.register_module_function(obj)
|
28
|
+
obj
|
29
|
+
end
|
30
|
+
end
|
31
|
+
|
32
|
+
class AttributeDirective
|
33
|
+
def method_name
|
34
|
+
sanitized_tag_signature || handler.call_params.first
|
35
|
+
end
|
36
|
+
|
37
|
+
def method_signature; method_name end
|
38
|
+
|
39
|
+
def create_attribute_data(object)
|
40
|
+
if object.tag(:constant)
|
41
|
+
object.property_type = :literal
|
42
|
+
else
|
43
|
+
object.property_type = :object
|
44
|
+
end
|
45
|
+
end
|
46
|
+
end
|
47
|
+
end
|
48
|
+
end
|