jsus 0.3.1 → 0.3.2

data/lib/jsus/tag.rb

@@ -3,8 +3,13 @@ module Jsus
   # Tag is basically just a string that contains a package name and a name for class
   # (or not necessarily a class) which the given SourceFile provides/requires/extends/replaces.
   #
+  # @example
+  # "Core/Class" is a tag
   class Tag
-    attr_accessor :package, :external # :nodoc:
+    # Owner package
+    attr_accessor :package
+    # Whether tag is external
+    attr_accessor :external
 
     # Constructors
 
@@ -14,6 +19,8 @@ module Jsus
     # The way it works may seem a bit tricky but actually it parses name/options
     # combinations in different ways and may be best described by examples:
     #
+    # @example
+    #
     #     a = Tag.new("Class")      # :package_name => "",     :name => "Class", :external => false
     #     b = Tag.new("Core/Class") # :package_name => "Core", :name => "Class", :external => true
     #     core = Package.new(...) # let's consider its name is 'Core'
@@ -23,8 +30,14 @@ module Jsus
     #     e = Tag.new("Core/Class", :package => mash) # :package_name => "Core", :name => "Class", :external => true
     #
     # Between all those, tags b,c,d and e are equal, meaning they all use
-    # the same spot in Hash or whatever else.
+    # the same spot in Hash or wherever else.
     #
+    # @param [String] tag name
+    # @param [Hash] options
+    # @option options [String] :package_name owner package name
+    # @option options [Jsus::Package] :package :owner package
+    # @option options [Boolean] :external whether tag is considered external
+    # @api public
     def initialize(name, options = {})
       normalized_options = Tag.normalize_name_and_options(name, options)
       [:name, :package, :package_name, :external].each do |field|
@@ -32,7 +45,9 @@ module Jsus
       end
     end
 
-    def self.new(tag_or_name, *args, &block) # :nodoc:
+    # When given a tag instead of tag name, just returns it.
+    # @api public
+    def self.new(tag_or_name, *args, &block)
       if tag_or_name.kind_of?(Tag)
         tag_or_name
       else
@@ -40,30 +55,29 @@ module Jsus
       end
     end
 
-    # alias for Tag.new
+    # Alias for Tag.new
+    # @api public
     def self.[](*args)
       new(*args)
     end
 
     # Public API
 
-    #
-    # Returns true if tag is external. See initialization for more info on cases.
-    #
+    # @returns [Boolean] whether tag is external
+    # @api public
     def external?
       !!external
     end
 
-    #
-    # Returns a well-formed name for the tag.
-    # Options:
-    # * +:short:+ -- whether the tag should try using short form
-    #
-    # Important note: only non-external tags support short forms.
-    #
-    #    Tag.new('Core/Class').name(:short => true) # => 'Core/Class'
-    #    core = Package.new(...) # let's consider its name is 'Core'
-    #    Tag.new('Core/Class', :package => core).name(:short => true) # => 'Class'
+    # @param [Hash] options
+    # @option options [Boolean] :short whether the tag should try using short form
+    # @note only non-external tags support short forms.
+    # @example
+    #     Tag.new('Core/Class').name(:short => true) # => 'Core/Class'
+    #     core = Package.new(...) # let's consider its name is 'Core'
+    #     Tag.new('Core/Class', :package => core).name(:short => true) # => 'Class'
+    # @return [String] a well-formed name for the tag.
+    # @api public
     def name(options = {})
       if !package_name || package_name.empty? || (options[:short] && !external?)
         @name
@@ -73,17 +87,19 @@ module Jsus
     end
     alias_method :to_s, :name
 
-    # Returns its package name or an empty string
+    # @returns [String] package name or an empty string
+    # @api public
     def package_name
       @package_name ||= (@package ? @package.name : "")
     end
 
-    # Returns true if its name is empty
+    # @return [Boolean] whether name is empty
+    # @api public
     def empty?
       @name.empty?
     end
 
-    # Returns true if it has the same name as other tag
+    # @api public
     def ==(other)
       if other.kind_of?(Tag)
         self.name == other.name
@@ -92,9 +108,26 @@ module Jsus
       end
     end
 
+    # @api semipublic
+    def eql?(other)
+      self.==(other)
+    end
+
+    # @api semipublic
+    def hash
+      self.name.hash
+    end
+
+    # @return [String] human-readable representation
+    # @api public
+    def inspect
+      "<Jsus::Tag: #{name}>"
+    end
+
     # Private API
 
-    def self.normalize_name_and_options(name, options = {}) # :nodoc:
+    # @api private
+    def self.normalize_name_and_options(name, options = {})
       result = {}
       name.gsub!(%r(^(\.)?/), "")
       if name.index("/")
@@ -112,39 +145,32 @@ module Jsus
       result
     end
 
-    def self.normalized_options_to_full_name(options) # :nodoc:
+    # @api private
+    def self.normalized_options_to_full_name(options)
       [options[:package_name], options[:name]].compact.join("/")
     end
 
-    def self.name_and_options_to_full_name(name, options = {}) # :nodoc:
+    # @api private
+    def self.name_and_options_to_full_name(name, options = {})
       normalized_options_to_full_name(normalize_name_and_options(name, options))
     end
 
-    def self.normalize_package_name(name) # :nodoc:
+    # @api private
+    def self.normalize_package_name(name)
       package_chunks = name.split("/")
       package_chunks.map do |pc|
         Jsus::Util::Inflection.random_case_to_mixed_case(pc)
       end.join("/")
     end # normalize_name
 
-    def package_name=(new_value) # :nodoc:
+    # @api private
+    def package_name=(new_value)
       @package_name = new_value
     end
 
-    def name=(new_value) # :nodoc:
+    # @api private
+    def name=(new_value)
       @name = new_value
     end
-
-    def eql?(other) # :nodoc:
-      self.==(other)
-    end
-
-    def hash # :nodoc:
-      self.name.hash
-    end
-
-    def inspect # :nodoc
-      "<Jsus::Tag: #{name}>"
-    end
   end
-end
+end

data/lib/jsus/util.rb

@@ -1,9 +1,11 @@
 module Jsus
+  # Utility namespace.
   module Util
-    autoload :Tree,       'jsus/util/tree'
-    autoload :Documenter, 'jsus/util/documenter'
-    autoload :Validator,  'jsus/util/validator'
-    autoload :Inflection, 'jsus/util/inflection'
-    autoload :FileCache,  'jsus/util/file_cache'
+    autoload :Tree,          'jsus/util/tree'
+    autoload :Documenter,    'jsus/util/documenter'
+    autoload :Validator,     'jsus/util/validator'
+    autoload :Inflection,    'jsus/util/inflection'
+    autoload :FileCache,     'jsus/util/file_cache'
+    autoload :CodeGenerator, 'jsus/util/code_generator'
   end # Util
-end # Jsus
+end # Jsus

data/lib/jsus/util/code_generator.rb

@@ -0,0 +1,21 @@
+module Jsus
+  module Util
+    # Code generation routines.
+    module CodeGenerator
+      class <<self
+        # @return [String] javascript for includes for a list of given paths
+        # @api public
+        def generate_includes(paths)
+          script = %{
+          (function(prefix, loader) {
+            var sources = %sources%;
+            if (!loader) loader = function(path) {
+              document.write('<scr' + 'ipt src="' + (prefix || '') + path + '"></script>');
+            }
+            for (var i = 0, j = sources.length; i < j; i++) loader(sources[i]);
+          })(window.prefix, window.loader);}.sub("%sources%", JSON.pretty_generate(paths))
+        end # generate_includes
+      end # class <<self
+    end # module CodeGenerator
+  end # module Util
+end # module Jsus

data/lib/jsus/util/documenter.rb

@@ -11,6 +11,10 @@ module Jsus
       attr_accessor :options
 
       # Constructor. Accepts options as the argument.
+      # @param [Hash] options
+      # @option options [Boolean] :highlight_source use syntax highlighting
+      #    (via pygments)
+      # @api public
       def initialize(options = DEFAULT_OPTIONS)
         require "murdoc"
         self.options = options
@@ -19,6 +23,9 @@ module Jsus
       end
 
       # Generates documentation tree into the given directory.
+      #
+      # @param [String] output directory
+      # @api public
       def generate(doc_dir = Dir.pwd)
         #FileUtils.rm_rf(doc_dir)
         FileUtils.mkdir_p(doc_dir)
@@ -41,6 +48,9 @@ module Jsus
       end
 
       # Adds a source file to the documented source tree
+      #
+      # @param [Jsus::SourceFile] pushed source
+      # @api public
       def <<(source) # :nodoc:
         filename = File.basename(source.filename)
         if source.package
@@ -52,25 +62,34 @@ module Jsus
         self
       end
 
-      def tree # :nodoc:
+      # @return [Jsus::Util::Tree] tree with all sources
+      # @api public
+      def tree
         @tree ||= Tree.new
       end
 
       # Scope for documentation in pathspec format. See Jsus::Util::Tree::Node#find_children_matching
+      # @return [Array] scope
+      # @api public
       def current_scope
         @current_scope ||= default_scope
       end
 
-      def default_scope # :nodoc:
+      # @return [Array] default documentation scope
+      # @api semipublic
+      def default_scope
         ["/**/*"]
       end
 
-      def current_scope=(scope) # :nodoc:
+      # @api semipublic
+      def current_scope=(scope)
         @current_scope = scope
       end
 
       # Sets documenter to exclusive scope for documentation.
       # Exclusive scope overrides all the other scopes.
+      # @param [Array, String] documentation scope
+      # @api public
       def only(scope)
         result = clone
         result.current_scope = [scope].flatten
@@ -79,18 +98,24 @@ module Jsus
 
       # Sets documenter to additive scope for documentation.
       # Additive scopes match any of the pathspecs given
+      #
+      # @param [Array, String] documentation scope
+      # @api public
       def or(scope)
         result = clone
         result.current_scope = current_scope + [scope].flatten
         result
       end
 
-      # Returns the tree with documented sources.
+      # @return [Jsus::Util::Tree] tree with documented sources only
+      # @api public
       def documented_sources
         @documented_sources ||= documented_sources!
       end
 
-      def documented_sources! # :nodoc:
+      # @see #documented_sources
+      # @api private
+      def documented_sources!
         doctree = Tree.new
         current_scope.map {|pathspec| tree.find_nodes_matching(pathspec) }.
                       flatten.each {|s| doctree.insert(s.full_path, s.value)}
@@ -99,6 +124,7 @@ module Jsus
 
       protected
 
+      # @api private
       def create_documentation_for_source(source, template) # :nodoc:
         skipped_lines = 0
         content = source.original_content.gsub(/\A\s*\/\*.*?\*\//m) {|w| skipped_lines += w.split("\n").size; "" }
@@ -106,13 +132,15 @@ module Jsus
         Murdoc::Formatter.new(template).render(:paragraphs => annotator.paragraphs, :header => source.header, :source => source, :skipped_lines => skipped_lines)
       end
 
+      # @api private
       def create_index_for_node(node, template) # :nodoc:
         Haml::Engine.new(template).render(self, :node => node)
       end
 
+      # @api private
       def file_from_contents(filename, contents) # :nodoc:
         File.open(filename, "w+") {|f| f << contents }
       end
     end
   end
-end
+end

data/lib/jsus/util/file_cache.rb

@@ -6,13 +6,18 @@ module Jsus
     #
     class FileCache
       # Initializes filecache to given directory
+      # @param [String] output directory
+      # @api public
       def initialize(path)
         @path = path
       end # initialize
 
       # Creates a file with given value for given key in cache directory
       #
-      # Returns actual path for stored file.
+      # @param [String] key
+      # @param [String] value
+      # @return [String] actual path for stored file.
+      # @api public
       def write(key, value)
         item_path = generate_path(key)
         FileUtils.mkdir_p(File.dirname(item_path))
@@ -20,21 +25,26 @@ module Jsus
         item_path
       end # write
 
-      # If file exists for given cache key, returns path to that file.
-      # If file doesn't exist, returns nil.
+      # @param [String] key
+      # @return [String, nil] path to cached file or nil
+      # @api public
       def read(key)
         item_path = generate_path(key)
         File.exists?(item_path) ? item_path : nil
       end # read
       alias_method :exists?, :read
 
-      # If file with given key exists, returns path to it.
-      # Otherwise, writes value of yielded block.
+      # @param [String] key
+      # @yield block with routine to call on cache miss
+      # @return [String] path to stored file
+      # @api public
       def fetch(key, &block)
         read(key) || write(key, yield)
       end # fetch
 
       # Deletes cache entry for given key.
+      # @param [String] key
+      # @api public
       def delete(key)
         item_path = generate_path(key)
         if File.exists?(item_path)
@@ -48,6 +58,7 @@ module Jsus
       #
       # Default strategy: append key to cache directory
       # (slashes are replaced with dots)
+      # @api private
       def generate_path(key)
         key = key.gsub(File::SEPARATOR, ".")
         File.join(@path, key)

data/lib/jsus/util/inflection.rb

@@ -4,31 +4,38 @@ module Jsus
     module Inflection
       class <<self
         # Converts strings with various punctuation to pascal case
+        # @example
         #     hello_world  => HelloWorld
         #     Oh.My.God    => OhMyGod
         #     iAmCamelCase => IAmCamelCase
         #     some_Weird_._punctuation => SomeWeirdPunctuation
+        # @api public
         def random_case_to_mixed_case(string)
           string.split(/[^a-zA-Z]+/).map {|chunk| capitalize(chunk) }.join
         end # random_case_to_mixed_case
 
         # Same as #random_case_to_mixed_case, but preserves dots
-        # color.fx => Color.Fx
+        # @example
+        #     color.fx => Color.Fx
+        # @api public
         def random_case_to_mixed_case_preserve_dots(string)
           string.split(".").map {|c| random_case_to_mixed_case(c) }.join(".")
         end # random_case_to_mixed_case
 
         # Capitalizes first letter (doesn't do anything else to other letters, unlike String#capitalize)
+        # @api public
         def capitalize(string)
           string[0,1].capitalize + string[1..-1].to_s
         end # capitalize
 
         # Downcases first letter
+        # @api public
         def decapitalize(string)
           string[0,1].downcase + string[1..-1].to_s
         end # decapitalize
 
         # Translates MixedCase string to camel-case
+        # @api public
         def snake_case(string)
           decapitalize(string.gsub(/(.)([A-Z])([a-z]+)/) {|_| "#{$1}_#{$2.downcase}#{$3}"}.
                               gsub(/[^A-Za-z_]+/, "_"))
@@ -36,4 +43,4 @@ module Jsus
       end # class <<self
     end # module Inflection
   end # module Util
-end # module Jsus
+end # module Jsus