yard-js 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (51) hide show
  1. checksums.yaml +7 -0
  2. data/LICENSE.txt +22 -0
  3. data/README.md +138 -0
  4. data/lib/yard-js.rb +30 -0
  5. data/lib/yard-js/code_objects.rb +8 -0
  6. data/lib/yard-js/code_objects/event_object.rb +11 -0
  7. data/lib/yard-js/code_objects/property_object.rb +83 -0
  8. data/lib/yard-js/core_ext/parsejs.rb +13 -0
  9. data/lib/yard-js/core_ext/yard.rb +17 -0
  10. data/lib/yard-js/core_ext/yard/code_objects.rb +45 -0
  11. data/lib/yard-js/core_ext/yard/registry.rb +29 -0
  12. data/lib/yard-js/core_ext/yard/tags.rb +48 -0
  13. data/lib/yard-js/core_ext/yard/templates.rb +116 -0
  14. data/lib/yard-js/core_ext/yard/yardoc.rb +23 -0
  15. data/lib/yard-js/handlers.rb +7 -0
  16. data/lib/yard-js/handlers/base.rb +53 -0
  17. data/lib/yard-js/handlers/class_handler.rb +43 -0
  18. data/lib/yard-js/handlers/comment_handler.rb +33 -0
  19. data/lib/yard-js/handlers/constant_handler.rb +50 -0
  20. data/lib/yard-js/handlers/instance_method_handler.rb +26 -0
  21. data/lib/yard-js/handlers/mixin_handler.rb +18 -0
  22. data/lib/yard-js/handlers/module_handler.rb +33 -0
  23. data/lib/yard-js/parser.rb +23 -0
  24. data/lib/yard-js/plugin.rb +23 -0
  25. data/lib/yard-js/tags.rb +37 -0
  26. data/lib/yard-js/version.rb +3 -0
  27. data/templates/default/class/setup.rb +11 -0
  28. data/templates/default/fulldoc/html/css/highlight.github.css +127 -0
  29. data/templates/default/fulldoc/html/css/style.css +10 -0
  30. data/templates/default/fulldoc/html/full_list_property.erb +12 -0
  31. data/templates/default/fulldoc/html/js/highlight.pack.js +1 -0
  32. data/templates/default/fulldoc/html/setup.rb +18 -0
  33. data/templates/default/layout/html/headers.erb +17 -0
  34. data/templates/default/layout/html/setup.rb +14 -0
  35. data/templates/default/method_details/setup.rb +13 -0
  36. data/templates/default/module/html/constructor_summary.erb +9 -0
  37. data/templates/default/module/html/events_details.erb +8 -0
  38. data/templates/default/module/html/events_summary.erb +20 -0
  39. data/templates/default/module/html/inherited_methods.erb +8 -0
  40. data/templates/default/module/html/inherited_properties.erb +8 -0
  41. data/templates/default/module/html/item_summary.erb +38 -0
  42. data/templates/default/module/html/method_summary.erb +11 -0
  43. data/templates/default/module/html/methods_details.erb +8 -0
  44. data/templates/default/module/html/properties_details.erb +8 -0
  45. data/templates/default/module/html/properties_summary.erb +11 -0
  46. data/templates/default/module/setup.rb +75 -0
  47. data/templates/default/tags/callback.erb +21 -0
  48. data/templates/default/tags/setup.rb +24 -0
  49. data/templates/default/tags/value.erb +6 -0
  50. data/yard-js.gemspec +15 -0
  51. metadata +92 -0
@@ -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
@@ -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.
@@ -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.
@@ -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,8 @@
1
+ module YARDJS
2
+ module CodeObjects
3
+ include YARD::CodeObjects
4
+ end
5
+ end
6
+
7
+ require_relative 'code_objects/event_object'
8
+ require_relative 'code_objects/property_object'
@@ -0,0 +1,11 @@
1
+ module YARDJS
2
+ module CodeObjects
3
+ class EventObject < Base
4
+ def constructor?; false end
5
+ def property_type; :event end
6
+ def aliases; [] end
7
+ def sep; '~' end
8
+ attr_accessor :parameters
9
+ end
10
+ end
11
+ end
@@ -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