docjs 0.1

data/test/js-files/nested_with_strings.js

@@ -0,0 +1,35 @@
+/**
+ * @function Outer
+ */
+var Outer = function(){
+  
+  /**
+   * This is an inner function
+   * @function .inner
+   */
+   var inner = function() {
+      string = "}}"
+   }
+   
+   
+  /**
+   * This is a second inner function
+   * @function .inner_two
+   */
+   var innerTwo = function() {
+      
+      var another_string = "({{}})\n\n\n)){()[])"
+   
+      /**
+       * And again, here is a inner function
+       * @object .foo
+       */
+        var foo = {
+          bar: 4,
+          baz: function() {}          
+        };   
+   
+   
+   }
+  
+};

data/test/js-files/prototype.js

@@ -0,0 +1,33 @@
+/**
+ * This function can be used like the following:
+ * @example
+ *   p = new Person("Peter Griffin");
+ *
+ * @constructor Person
+ */
+var Person = function(name) {
+
+  this.name = name;
+
+}; 
+ 
+/**
+ * Single argument version. Only supplies the function to which this object
+ * acts as a prototype
+ *
+ * @prototype Person
+ */
+Person.prototype = {
+
+  /**
+   * Alerts a string containing the name of the person
+   *
+   * @function .sayHello
+   */
+  sayHello: function() {
+      
+    alert("Hello my name is " + this.name);
+    
+  }
+
+};

data/test/js-files/simple.js

@@ -0,0 +1,17 @@
+/**
+ * Some documentation
+ * And some more
+ *
+ * @first tokenline
+ * @second tokenline, which should be a multiline token
+ *   because it is intended with at least 2 spaces and
+ *   it won't stop, until there is an empty line, or a
+ *   new token
+ *
+ * And another docline
+ */
+var foo = {
+
+  property: "A String with //something, that /*looks like a comment */"  
+  
+};

data/test/js-files/tokens.js

@@ -0,0 +1,32 @@
+/**
+ * This is some documentation
+ * with multiple lines
+ * 
+ * @function say_hello
+ *
+ * @public
+ * @param [String] foo some parameter
+ * @return [String, Integer] returns a string "hello"
+ */
+ var say_hello = function(foo) {
+  return "hello";
+ };
+ 
+ /**
+ * This is some documentation
+ * with multiple lines
+ * 
+ * @object FOO
+ */
+ var FOO = {};
+ 
+ /**
+ * This is some documentation
+ * with multiple lines
+ * 
+ * @constructor FOO.bar.some_function
+ * @param [String] parameter1 The first parameter
+ */
+ var FOO.some_function = function(parameter1) {
+  // some comment without tokens
+ };

data/test/parser/comments_in_strings.rb

@@ -0,0 +1,51 @@
+#encoding utf-8
+
+require_relative '../../lib/parser/parser'
+
+describe Parser::Parser, ".parse" do
+
+  context "Parsing comments_in_strings.js" do
+
+    before do  
+      stream = File.read File.expand_path('../../js-files/comments_in_strings.js', __FILE__)
+      @parser = Parser::Parser.new stream
+      @comments = @parser.parse
+    end
+    
+    subject { @comments }
+    
+    it "should find 1 comment" do
+      subject.length.should == 1
+    end
+    
+    
+    describe "The First Comment" do
+    
+      subject { @comments.first }
+      
+      it "should contain 1 docline and 1 tokenline" do
+        subject.doclines.length.should == 1
+        subject.tokenlines.length.should == 1
+      end
+      
+      it "should have got correct tokenline-contents" do
+        tokens = subject.tokenlines        
+        tokens[0].token.should == :object        
+        tokens[0].content.should == "only_one\n"
+      end      
+      
+      it "should have got correct source" do
+        subject.source.should == "  var innerTwo = function() {
+      
+      var another_string = \"({})\\n\\n\\n)){()[])\"
+   
+      single_string = '// @object .foo'
+        var foo = {
+          bar: 4,
+          baz: function() {}          
+        };      
+   } "
+      end
+    end
+  end
+end

data/test/parser/intelligent_skip_until.rb

@@ -0,0 +1,110 @@
+require_relative '../../lib/parser/parser'
+
+describe StringScanner, "#intelligent_skip_until" do
+  
+  context "closing braces in strings" do  
+    before do
+      @scanner = StringScanner.new "Foo bar baz \"this is a) string\" this is not) - and some more"
+      @scanner.intelligent_skip_until /\)/
+    end
+    
+    it "should find ) at pos 44" do
+      @scanner.pos.should == 44
+      @scanner.matched.should == ")"
+    end  
+  end
+  
+  
+  context "closing braces in single-strings" do  
+    before do
+      @scanner = StringScanner.new "Foo bar baz 'this is a) string' this is not) - and some more"
+      @scanner.intelligent_skip_until /\)/
+    end
+    
+    it "should find ) at pos 44" do
+      @scanner.pos.should == 44
+      @scanner.matched.should == ")"
+    end  
+  end
+  
+  
+  context "escaped string-ends" do  
+    before do
+      @scanner = StringScanner.new "Foo bar baz \"this is a) string\\\" this is not)\" - and )some more"
+      @scanner.intelligent_skip_until /\)/
+    end
+    
+    it "should find ) at pos 54" do
+      @scanner.pos.should == 54
+      @scanner.matched.should == ")"
+    end  
+  end
+  
+  
+  context "regular expressions" do  
+    before do
+      @scanner = StringScanner.new "Foo bar baz /(a-z)_[\\(\\)]/ix - and )some more"
+      @scanner.intelligent_skip_until /\)/
+    end
+    
+    it "should find ) at pos 36" do
+      @scanner.pos.should == 36
+      @scanner.matched.should == ")"
+    end  
+  end
+  
+  
+  context "escaped regular expressions" do  
+    before do
+      @scanner = StringScanner.new "Foo bar baz /(a-z)_[\\(\\)]\\/foo/ix - and )some more"
+      @scanner.intelligent_skip_until /\)/
+    end
+    
+    it "should find ) at pos 41" do
+      @scanner.pos.should == 41
+      @scanner.matched.should == ")"
+    end  
+  end
+  
+  
+  context "single line comments" do  
+    before do
+      @scanner = StringScanner.new "Foo bar baz //(Oh a comment))\n - and )some more"
+      @scanner.intelligent_skip_until /\)/
+    end
+    
+    it "should find ) at pos 38" do
+      @scanner.pos.should == 38
+      @scanner.matched.should == ")"
+    end     
+  end
+  
+  
+  context "multi line comments" do  
+    before do
+      @scanner = StringScanner.new "Foo bar baz 
+/**
+ * (Oh a comment))
+ */ - and )some more"
+      @scanner.intelligent_skip_until /\)/
+    end
+    
+    it "should find ) at pos 47" do
+      @scanner.pos.should == 47
+      @scanner.matched.should == ")"
+    end  
+  end
+  
+  context "not ending single line comments" do  
+    before do
+      @scanner = StringScanner.new "Foo bar baz //(Oh a comment)) - and )some more"
+    end
+    
+    it "should raise an exception" do
+      should_raise StringScanner::Error do
+        @scanner.intelligent_skip_until /\)/
+      end
+    end     
+  end
+
+end

data/test/parser/parser.rb

@@ -0,0 +1,273 @@
+#encoding utf-8
+
+require_relative '../../lib/parser/parser'
+
+describe Parser::Parser, ".parse" do
+
+  context "Parsing simple.js" do
+
+    before do  
+      stream = File.read File.expand_path('../../js-files/simple.js', __FILE__)
+      @parser = Parser::Parser.new stream
+      @comments = @parser.parse
+    end
+    
+    subject { @comments }
+    
+    it "should find 1 comment" do
+      subject.length.should == 1
+    end
+    
+    
+    describe "The First Comment" do
+    
+      subject { @comments.first }
+      
+      it "should contain 3 doclines and 2 tokenlines" do
+        subject.doclines.length.should == 5
+        subject.tokenlines.length.should == 2
+      end
+      
+      it "should have got correct tokenline-contents" do
+        tokens = subject.tokenlines
+        
+        tokens[0].token.should == :first
+        tokens[1].token.should == :second
+        
+        tokens[0].content.should == "tokenline\n"
+        tokens[1].content.should == "tokenline, which should be a multiline token\nbecause it is intended with at least 2 spaces and\nit won't stop, until there is an empty line, or a\nnew token\n"
+      end      
+    end
+  end
+
+
+  context "Parsing a File with nested comments" do
+
+    before do  
+      @path = File.expand_path('../../js-files/nested.js', __FILE__)
+      stream = File.read @path
+      @parser = Parser::Parser.new(stream, :filepath => @path)
+      @comments = @parser.parse
+    end
+    
+    subject { @comments }
+    
+    it "should find 1 root comments" do
+      subject.length.should == 1
+    end
+    
+    
+    describe "the first comment" do
+    
+      subject { @comments.first }
+      
+      it "should containt 0 doclines and 1 tokenline" do
+        subject.doclines.length.should == 0
+        subject.tokenlines.length.should == 1
+      end
+      
+      it "should have got correct tokenline-contents" do
+        tokens = subject.tokenlines        
+        tokens[0].token.should == :function        
+        tokens[0].content.should == "Outer\n"
+      end
+      
+      it "should start at line 4" do
+        subject.line_start.should == 4
+      end
+      
+      it "should contain the right filepath" do
+        subject.filepath.should == @path
+      end
+      
+      it "should contain the right source" do
+        subject.source.should == "var Outer = function(){
+  
+  /**
+   * This is an inner function
+   * @function .inner
+   */
+   var inner = function() {
+   
+   }
+   
+   
+  /**
+   * This is a second inner function
+   * @function .inner_two
+   */
+   var innerTwo = function() {
+   
+   
+      /**
+       * And again, here is a inner function
+       * @object .foo
+       */
+        var foo = {
+          bar: 4,
+          baz: function() {}          
+        };   
+   
+   
+   }
+  
+};"
+      end      
+      
+      it "should contain 2 child-comments" do 
+        subject.children.length.should == 2
+      end      
+    end
+    
+    
+    describe "the first inner comment" do
+    
+      subject { @comments.first.children.first }
+      
+      it "should contain 1 doclines and 1 tokenline" do
+        subject.doclines.length.should == 1
+        subject.tokenlines.length.should == 1
+      end
+      
+      it "should have got correct tokenline-contents" do
+        tokens = subject.tokenlines        
+        tokens[0].token.should == :function        
+        tokens[0].content.should == ".inner\n"
+      end
+      
+      it "should start at line 10" do
+        subject.line_start.should == 10
+      end
+      
+      it "should contain the right filepath" do
+        subject.filepath.should == @path
+      end
+            
+    end
+        
+        
+    describe "the second inner comment" do
+    
+      subject { @comments.first.children[1] }
+      
+      it "should contain 1 doclines and 1 tokenline" do
+        subject.doclines.length.should == 1
+        subject.tokenlines.length.should == 1
+      end
+      
+      it "should have got correct tokenline-contents" do
+        tokens = subject.tokenlines        
+        tokens[0].token.should == :function        
+        tokens[0].content.should == ".inner_two\n"
+      end
+      
+      it "should start at line 19" do
+        subject.line_start.should == 19
+      end
+      
+      it "should contain the right filepath" do
+        subject.filepath.should == @path
+      end  
+      
+    end
+    
+    
+    describe "the most inner comment" do
+    
+      subject { @comments.first.children[1].children.first }
+      
+      it "should contain 1 doclines and 1 tokenline" do
+        subject.doclines.length.should == 1
+        subject.tokenlines.length.should == 1
+      end
+      
+      it "should have got correct tokenline-contents" do
+        tokens = subject.tokenlines        
+        tokens[0].token.should == :object        
+        tokens[0].content.should == ".foo\n"
+      end
+      
+      it "should start at line 26" do
+        subject.line_start.should == 26
+      end
+      
+      it "should contain the right filepath" do
+        subject.filepath.should == @path
+      end      
+      
+    end
+    
+  end
+
+
+
+  context "being confronted with windows-linebreaks \\r \\n" do
+
+    before do  
+      @parser = Parser::Parser.new("/**\r\n *\r\n * @tokenline with something fancy\r\n * @multiline token with\r\n *   continue over line end\r\n *  */")
+      @comments = @parser.parse
+    end  
+
+    it "should parse tokenlines correct" do
+      tokens = @comments.first.tokenlines
+      
+      tokens[0].token.should == :tokenline
+      tokens[1].token.should == :multiline
+      
+      tokens[0].content.should == "with something fancy\n"
+      tokens[1].content.should == "token with\ncontinue over line end\n"
+    end
+    
+  end
+  
+  context "multiline tokens with empty first line" do
+
+    before do  
+      @comments = Parser::Parser.new("
+/**
+ * @multiline
+ *  this is a multiline token with
+ *  empty first line
+ */
+").parse
+    end  
+
+    describe "the multiline token" do
+
+      subject { @comments.first.tokenlines[0] }
+      
+      it "should be named :multiline" do
+        subject.token.should == :multiline
+        subject.content.should == "\nthis is a multiline token with\nempty first line\n"
+      end
+    end  
+  end
+  
+  
+  context "parsing multibyte character" do
+=begin
+    before do  
+
+      @parser = Parser::Parser.new("/**
+ *
+ * @tokenline ÜÄÖÖüäöüöäßø
+ * @multiline token with
+ *   continue over line end
+ *  
+ */
+Foo Bar")
+      @comments = @parser.parse
+    end  
+
+    subject { @comments.first }
+  
+    it "should find the correct source" do
+      subject.source.should == "Foo Bar"
+    end
+    
+=end
+    pending("There are Problems with utf-8 encoded string")
+  
+  end  
+  
+end