Better docs for TypeParser. (b73e984b) · Commits · extjs / jsduck

lib/jsduck/type_parser.rb

+36 −8

Original line number	Diff line number	Diff line
		@@ -2,17 +2,43 @@ require 'strscan'

		module JsDuck

		# Validates the syntax of type definitions
		# Validates the syntax of type definitions.
		#
		# Quick summary of supported types:
		# The parser supports a combination of two syntaxes:
		#
		# - SomeType
		# - Name.spaced.Type
		# - Number[]
		# - String/RegExp
		# - Type...
		# 1. Traditional type expressions found in ExtJS code:
		#
		# Details are covered in spec.
		# SomeType
		# Name.spaced.Type
		# Number[]
		# String/RegExp
		# Type...
		#
		# 2. Google Closure Compiler Type Expressions:
		#
		# boolean
		# Window
		# goog.ui.Menu
		#
		# Array.<string>
		# Object.<string, number>
		#
		# (number\|boolean)
		# ?number
		# !Object
		# ...number
		# *
		#
		# function(string, boolean): number
		# function(new:goog.ui.Menu, string)
		# function(this:goog.ui.Menu, string)
		# function(?string=, number=)
		#
		# Currently not supported:
		#
		# function(string, ...[number])
		#
		# {myNum: number, myObject}
		#
		class TypeParser
		# Allows to check the type of error that was encountered.
		@@ -58,6 +84,8 @@ module JsDuck
		return @input.eos?
		end

		private

		#
		# <alteration-type> ::= <varargs-type> [ ("/" \| "\|") <varargs-type> ]*
		#

spec/type_parser_spec.rb

+76 −68

Original line number	Diff line number	Diff line
		@@ -145,33 +145,37 @@ describe JsDuck::TypeParser do
		parse("!?String").should == false
		end

		it "matches alteration with pipe" do
		describe "alteration" do
		it "matches pipes" do
		parse("String\|Number\|RegExp").should == true
		end

		it "matches alteration with extra spacing" do
		it "matches with extra spacing" do
		parse(" String \| Number ").should == true
		end
		end

		it "matches union of one simple type" do
		describe "union" do
		it "matches one simple type" do
		parse("(String)").should == true
		end

		it "matches union of two simple types" do
		it "matches two simple types" do
		parse("(String\|Number)").should == true
		end

		it "matches union type in varargs context" do
		it "matches in varargs context" do
		parse("...(String\|Number)").should == true
		end

		it "matches nested union type" do
		it "natches with nested union" do
		parse("(String\|(Number\|RegExp))").should == true
		end

		it "matches union with extra spacing" do
		it "matches with extra spacing" do
		parse("( String \| Number )").should == true
		end
		end

		# This is handled inside DocParser, when it's detected over there
		# the "=" is removed from the end of type definition, so it should
		@@ -184,73 +188,77 @@ describe JsDuck::TypeParser do
		parse("String=").should == false
		end

		it "matches single type argument" do
		describe "type arguments" do
		it "matches single" do
		parse("Array.<Number>").should == true
		end

		it "matches multiple type arguments" do
		it "matches multiple" do
		parse("Ext.Element.<String,Number>").should == true
		end

		it "matches type arguments with extra spacing" do
		it "matches with extra spacing" do
		parse("Ext.Element.< String , Number >").should == true
		end

		it "matches nested type arguments" do
		it "matches with nested type arguments" do
		parse("Array.<Array.<String>\|Array.<Number>>").should == true
		end

		it "doesn't accept type arguments on type union" do
		parse("(Array,RegExp).<String>").should == false
		it "doesn't accept on type union" do
		parse("(Array\|RegExp).<String>").should == false
		end

		it "doesn't accept empty type arguments block" do
		it "doesn't accept empty" do
		parse("Array.<>").should == false
		end
		end

		it "matches empty function type" do
		describe "function type" do
		it "matches empty" do
		parse("function()").should == true
		end

		it "matches function type with arguments" do
		it "matches arguments" do
		parse("function(String,Number)").should == true
		end

		it "matches function type with return type" do
		it "matches return type" do
		parse("function():Number").should == true
		end

		it "matches function type with varargs" do
		it "matches with varargs" do
		parse("function(...Number)").should == true
		end

		it "matches function type with nullable/non-nullable arguments" do
		it "matches nullable/non-nullable arguments" do
		parse("function(!String, ?Number)").should == true
		end

		it "matches function type with optional argument" do
		it "matches optional argument" do
		parse("function(Number=)").should == true
		end

		it "matches function type with this: argument" do
		it "matches this: argument" do
		parse("function(this:Array, Number)").should == true
		end

		it "matches function type with new: argument" do
		it "matches new: argument" do
		parse("function(new:Array)").should == true
		end

		it "matches function type with this: argument + ws" do
		it "matches this: argument + ws" do
		parse("function(this : Array, Number)").should == true
		end

		it "matches function type with new: argument + ws" do
		it "matches new: argument + ws" do
		parse("function(new : Array)").should == true
		end

		it "matches function type with extra whitespace" do
		it "matches with extra whitespace" do
		parse("function( ) : Array").should == true
		end
		end

		it "always matches primitive types" do
		parse("boolean").should == true