yard-js 0.1.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 397d27d635f2aaba7eb2e4d6a4c9e4db57189922
+  data.tar.gz: 5c4715dcbba5a68fb4815e9ea91148437444229e
+SHA512:
+  metadata.gz: decba19d8c378a1e31dc3aaa8506e87196dd4beaf9e3ce06bcc6c16120bb923e9a4ff34bf161e2d2132c8527bd58d2cb89e6993f5e09b6bfc8fa08f82b0409e1
+  data.tar.gz: e2687e8cfb0fb4ab5878e6b34f11f6ad822eb038d4df56fd2e34b8642517d8585f4b6fdd132d96e1b6b4a99fa9e98ea242280ced26547ee4c847b2833eacaf00

data/LICENSE.txt

@@ -0,0 +1,22 @@
+Copyright (c) 2007-2013 Loren Segal
+
+Permission is hereby granted, free of charge, to any person
+obtaining a copy of this software and associated documentation
+files (the "Software"), to deal in the Software without
+restriction, including without limitation the rights to use,
+copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the
+Software is furnished to do so, subject to the following
+conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES
+OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT
+HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY,
+WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,138 @@
+# YARD for JavaScript
+
+A [YARD](http://yardoc.org) plugin that adds support for documenting
+JavaScript source files with minimal amount of manual declarations, support
+for YARD syntax, and templates for displaying HTML documentation.
+
+The plugin relies on certain conventional syntaxes for declaring classes and
+mixins. See the "Generating documentation" section below for how to customize
+this.
+
+## Documenting with yard-js
+
+Documenting with `yard-js` should be similar to documenting with YARD.
+Information on how to document with YARD can be found in YARD's
+[Getting Started Guide](http://rubydoc.org/docs/yard/file/docs/GettingStarted.md).
+Just like in Ruby, you will document methods or classes by adding docstrings
+above the definition. Unlike jsdoc, you do not need to explicitly denote the
+class name or details, as these will be automatically detected by YARD. For
+instance, the following File class can be documented like so:
+
+```js
+/**
+ * This class represents files on disk.
+ *
+ * @see FileSystem
+ */
+inherit(IO, {
+  /**
+   * Opens a new file at the location of `filename`
+   *
+   * @param filename [String] the location on disk of the file to open.
+   * @param access [String] a combination or 'r' and 'w' for access modes.
+   */
+  constructor: function (filename, access) { ... },
+
+  /**
+   * Reads from the open file
+   *
+   * @param numBytes [number] the number of bytes to read. Leave this
+   *   empty to read all remaining data.
+   * @return [Buffer] the data read from disk as a buffer.
+   */
+  read: function (numBytes) { ... }
+});
+```
+
+All [macros and tags](http://rubydoc.org/docs/yard/file/docs/Tags.md) available
+in YARD are available in `yard-js`.
+
+## Requirements
+
+YARD for JavaScript relies on the following software:
+
+* [Ruby 1.9.x](http://ruby-lang.org)
+* [Bundler](http://gembundler.com)
+* [`yard` RubyGem](http://rubygems.org/gems/yard)
+* [`parsejs` library](http://rubygems.org/gems/parsejs)
+
+Note that installing Ruby is not covered in the installation section.
+
+## Installing
+
+To install, clone the repository and `bundle install` to install dependencies:
+
+```sh
+$ git clone git://github.com/lsegal/yard-js
+$ cd yard-js
+$ bundle install
+```
+
+## Usage
+
+To generate documentation for a project, change into the project directory
+and type:
+
+```sh
+$ yard -m markdown -e /path/to/yard-js/lib/yard-js
+```
+
+To take advantage of class detection you will also need to customize the
+expressions used by `yard-js` to find class definitions. These are done through
+the following command line arguments:
+
+`--define-class-expr`: The syntax used in your code to define a class. For
+example, `--define-class-expr inherit` will look for the following statement:
+
+```js
+inherit(SuperClass, {
+  // class implementation
+  constructor: function() { /* constructor function */ },
+  foo: function() { /* an instance method */ }
+});
+```
+
+`--update-class-expr`: The syntax used in your code to update the class object
+itself (also known as class level methods/properties). For example,
+`--update-class-expr update` will detect the following block as a set of class
+methods:
+
+```js
+update(MyClass, {
+  bar: function() { /* a method only available as MyClass.bar() */ }
+});
+```
+
+`--mixin-module-expr`: The syntax used to detect modules mixed into a class.
+For example, `--mixin-module-expr mixin` will detect:
+
+```js
+mixin(MyClass, SomeMixin);
+```
+
+To simplify setting these values, you can add these command line arguments
+to a `.yardopts` file in the root level of your project, for example:
+
+    --define-class-expr inherit
+    --update-class-expr update
+    --mixin-module-expr mixin
+
+Note that by default YARD uses RDoc comment formatting. This is overridden in
+the above example by adding `-m markdown` to use markdown formatting for
+documentation comments.
+
+## Known Issues
+
+1. This plugin is currently not a true "plugin". This will require availability
+   as a RubyGem, which will happen soon.
+
+2. This plugin is currently not compatible with the YARD server architecture.
+   This is being worked on.
+
+3. This plugin cannot document Ruby code alongside JavaScript code due to the
+   way it modifies YARD internals. Making yard-js work side-by-side Ruby code
+   will be a long-term goal.
+
+## License
+
+`yard-js` is available under the MIT license.

data/lib/yard-js.rb

@@ -0,0 +1,30 @@
+require 'ostruct'
+
+module YARDJS
+  class Options
+    %w(define_class_expression
+       update_class_expression
+       mixin_module_expression).each do |name|
+      attr_reader(name)
+      define_method("#{name}=") do |value|
+        instance_variable_set("@#{name}", /\A#{value}\Z/)
+      end
+    end
+
+    def initialize
+      self.define_class_expression ||=
+        ENV['DEFINE_CLASS_EXPR'] || 'inherit'
+      self.update_class_expression ||=
+        ENV['UPDATE_CLASS_EXPR'] || 'update'
+      self.mixin_module_expression ||=
+        ENV['MIXIN_MODULE_EXPR'] || 'mixin'
+    end
+  end
+
+  def self.options
+    @options ||= Options.new
+  end
+end
+
+require_relative 'yard-js/plugin'
+require_relative 'yard-js/version'

data/lib/yard-js/code_objects.rb

@@ -0,0 +1,8 @@
+module YARDJS
+  module CodeObjects
+    include YARD::CodeObjects
+  end
+end
+
+require_relative 'code_objects/event_object'
+require_relative 'code_objects/property_object'

data/lib/yard-js/code_objects/event_object.rb

@@ -0,0 +1,11 @@
+module YARDJS
+  module CodeObjects
+    class EventObject < Base
+      def constructor?; false end
+      def property_type; :event end
+      def aliases; [] end
+      def sep; '~' end
+      attr_accessor :parameters
+    end
+  end
+end

data/lib/yard-js/code_objects/property_object.rb

@@ -0,0 +1,83 @@
+module YARDJS
+  module CodeObjects
+    class PropertyObject < Base
+      attr_accessor :parameters, :property_type
+
+      def aliases; [] end
+
+      # @return whether or not the method is the #initialize constructor method
+      def constructor?
+        name == :constructor && namespace.is_a?(YARD::CodeObjects::ClassObject)
+      end
+
+      def relative_path(other)
+        case other
+        when PropertyObject
+          if other.parent == parent
+            other.name.to_s
+          else
+            other.path
+          end
+        else
+          if parent == other
+            other.name.to_s
+          else
+            other.path
+          end
+        end
+      end
+
+      def scope; :class end
+      def attr_info; nil end
+
+      # @return [Boolean] whether or not this method was created as a module
+      #   function
+      # @since 0.8.0
+      def module_function?
+        false
+      end
+
+      # @return [Boolean] whether the method is a writer attribute
+      # @since 0.5.3
+      def writer?
+        true
+      end
+
+      # @return [Boolean] whether the method is a reader attribute
+      # @since 0.5.3
+      def reader?
+        true
+      end
+
+      # Tests if the object is defined as an attribute in the namespace
+      # @return [Boolean] whether the object is an attribute
+      def is_attribute?
+        false
+      end
+
+      # Tests if the object is defined as an alias of another method
+      # @return [Boolean] whether the object is an alias
+      def is_alias?
+        false
+      end
+
+      # Tests boolean {#explicit} value.
+      #
+      # @return [Boolean] whether the method is explicitly defined in source
+      def is_explicit?
+        true
+      end
+
+      # @return [MethodObject] the object that this method overrides
+      # @return [nil] if it does not override a method
+      # @since 0.6.0
+      def overridden_method
+        nil
+      end
+
+      def value
+        tag(:value) ? tag(:value).text : ''
+      end
+    end
+  end
+end

data/lib/yard-js/core_ext/parsejs.rb

@@ -0,0 +1,13 @@
+$:.unshift(File.expand_path('~/parsejs/lib'))
+
+require 'parsejs'
+require 'parsejs/stringifier'
+
+class ParseJS::AST::Node
+  def line; 0 end
+  def show; ParseJS::Stringifier.to_string(self) end
+  def comments_hash_flag; nil end
+  def comments_range; nil end
+  alias source show
+  attr_accessor :comments
+end

data/lib/yard-js/core_ext/yard.rb

@@ -0,0 +1,17 @@
+require 'yard'
+
+require_relative 'yard/code_objects'
+require_relative 'yard/registry'
+require_relative 'yard/tags'
+require_relative 'yard/templates'
+require_relative 'yard/yardoc'
+
+YARD::CodeObjects::NSEP.replace('.')
+YARD::CodeObjects.send(:remove_const, :NSEPQ)
+YARD::CodeObjects::NSEPQ = Regexp.quote(YARD::CodeObjects::NSEP)
+YARD::CodeObjects::CSEP.replace('.')
+YARD::CodeObjects.send(:remove_const, :CSEPQ)
+YARD::CodeObjects::CSEPQ = Regexp.quote(YARD::CodeObjects::CSEP)
+YARD::CodeObjects::ISEP.replace('.')
+YARD::CodeObjects.send(:remove_const, :ISEPQ)
+YARD::CodeObjects::ISEPQ = Regexp.quote(YARD::CodeObjects::ISEP)

data/lib/yard-js/core_ext/yard/code_objects.rb

@@ -0,0 +1,45 @@
+require 'yard'
+
+module YARD
+  module CodeObjects
+    class Base
+      alias old_relative_path relative_path
+      def relative_path(other)
+        if other.is_a?(NamespaceObject)
+          other.path
+        else
+          old_relative_path(other)
+        end
+      end
+    end
+
+    class NamespaceObject
+      def properties
+        children.select {|o| o.type == :property }
+      end
+
+      def events
+        children.select {|o| o.type == :event }
+      end
+
+      def constants(opts = {})
+        properties.select {|o| o.has_tag?(:constant) }
+      end
+
+      def relative_path(other)
+        if self == other.parent
+          other.name.to_s
+        else
+          other.path
+        end
+      end
+    end
+
+    class ClassObject
+      def initialize(namespace, name, *args, &block)
+        super
+        self.superclass = "Object"
+      end
+    end
+  end
+end

data/lib/yard-js/core_ext/yard/registry.rb

@@ -0,0 +1,29 @@
+module YARD
+  module Registry
+    def self.resolve(namespace, name, inheritance = false, proxy_fallback = false, type = nil)
+      if namespace.is_a?(CodeObjects::Proxy)
+        return proxy_fallback ? CodeObjects::Proxy.new(namespace, name, type) : nil
+      end
+
+      if namespace == :root || !namespace
+        namespace = root
+      else
+        namespace = namespace.parent until namespace.is_a?(CodeObjects::NamespaceObject)
+      end
+      orignamespace = namespace
+
+      name = name.to_s.sub(/^\./, '')
+      nss = namespace.path.split('.')
+      nss = [] if nss == ['']
+      while nss.size >= 0
+        if obj = at((nss + [name]).compact.join('.'))
+          return obj
+        end
+        break if nss.size == 0
+        nss.pop
+      end
+
+      proxy_fallback ? CodeObjects::Proxy.new(orignamespace, name, type) : nil
+    end
+  end
+end

data/lib/yard-js/core_ext/yard/tags.rb

@@ -0,0 +1,48 @@
+module YARD
+  module Tags
+    class MethodDirective
+      def method_name
+        sig = sanitized_tag_signature
+        if sig
+          sig[/\A\s*([^\(; \t]+)/, 1]
+        else
+          handler.call_params.first
+        end
+      end
+
+      def create_object
+        name = method_name
+        visibility = parser.state.visibility || handler.visibility
+        ns = CodeObjects::NamespaceObject === object ? object : handler.namespace
+        obj = YARDJS::CodeObjects::PropertyObject.new(ns, name)
+        handler.register_file_info(obj)
+        handler.register_source(obj)
+        handler.register_visibility(obj, visibility)
+        handler.register_group(obj)
+        obj.signature = method_signature
+        obj.parameters = OverloadTag.new(:overload, method_signature).parameters
+        obj.docstring = Docstring.new!(parser.text, parser.tags, obj,
+          parser.raw_text)
+        obj.property_type = :function
+        handler.register_module_function(obj)
+        obj
+      end
+    end
+
+    class AttributeDirective
+      def method_name
+        sanitized_tag_signature || handler.call_params.first
+      end
+
+      def method_signature; method_name end
+
+      def create_attribute_data(object)
+        if object.tag(:constant)
+          object.property_type = :literal
+        else
+          object.property_type = :object
+        end
+      end
+    end
+  end
+end