ghazel-ffi-clang 0.2.0.1

data/lib/ffi/clang/translation_unit.rb

@@ -0,0 +1,142 @@
+# Copyright, 2010-2012 by Jari Bakken.
+# Copyright, 2013, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# Copyright, 2014, by Masahiro Sano.
+# 
+# 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.
+
+require 'ffi/clang/lib/translation_unit'
+require 'ffi/clang/cursor'
+require 'ffi/clang/file'
+require 'ffi/clang/token'
+
+module FFI
+	module Clang
+		class TranslationUnit < AutoPointer
+			def initialize(pointer, index)
+				super pointer
+				@index = index
+			end
+
+			def self.release(pointer)
+				Lib.dispose_translation_unit(pointer)
+			end
+
+			def self.default_editing_translation_unit_options
+				bitmask = Lib.default_editing_translation_unit_options
+				Lib.opts_from Lib::TranslationUnitFlags, bitmask
+			end
+
+			def default_save_options
+				bitmask = Lib.default_save_options(self)
+				Lib.opts_from Lib::SaveTranslationUnitFlags, bitmask
+			end
+
+			def save(filename, opts = {})
+				ret = Lib.save_translation_unit(self, filename, 0)
+				sym = Lib::SaveError[ret]
+				raise Error, "unknown return values: #{ret} #{sym.inspect}" unless sym
+				raise Error, "save error: #{sym.inspect}, filename: #{filename}" if sym != :none
+			end
+
+			def default_reparse_options
+				bitmask = Lib.default_save_options(self)
+				Lib.opts_from Lib::ReparseFlags, bitmask
+			end
+
+			def reparse(unsaved = [], opts = {})
+				unsaved_files = UnsavedFile.unsaved_pointer_from(unsaved)
+				if Lib.reparse_translation_unit(self, unsaved.size, unsaved_files, 0) != 0
+					raise Error, "reparse error"
+				end
+			end
+
+			def diagnostics
+				n = Lib.get_num_diagnostics(self)
+			
+				n.times.map do |i|
+					Diagnostic.new(self, Lib.get_diagnostic(self, i))
+				end
+			end
+
+			def cursor(location = nil)
+				if location.nil?
+					Cursor.new Lib.get_translation_unit_cursor(self), self
+				else
+					Cursor.new Lib.get_cursor(self, location.location), self
+				end
+			end
+
+			def location(file, line, column)
+				ExpansionLocation.new Lib.get_location(self, file, line, column)
+			end
+
+			def location_offset(file, offset)
+				ExpansionLocation.new Lib.get_location_offset(self, file, offset)
+			end
+
+			def file(file_name)
+				File.new(Lib.get_file(self, file_name), self)
+			end
+
+			def spelling
+				Lib.get_translation_unit_spelling(self)
+			end
+
+			def resource_usage
+				FFI::Clang::TranslationUnit::ResourceUsage.new Lib.resource_usage(self)
+			end
+
+			def tokenize(range)
+				token_ptr = MemoryPointer.new :pointer
+				uint_ptr = MemoryPointer.new :uint
+				Lib.tokenize(self, range.range, token_ptr, uint_ptr)
+				Tokens.new(token_ptr.get_pointer(0), uint_ptr.get_uint(0), self)
+			end
+
+			class ResourceUsage < AutoPointer
+				def initialize(resource_usage)
+					# CXResourceUsage is returned by value and should be freed explicitly.
+					# Get FFI::pointer of the data so that the data is handled by AutoPointer.
+					pointer = FFI::Pointer.new(resource_usage.to_ptr)
+					super(pointer)
+					@resource_usage = resource_usage
+				end
+
+				def self.release(pointer)
+					# clang_disposeCXTUResourceUsage requires value type, so create it by pointer
+					Lib.dispose_resource_usage(Lib::CXTUResourceUsage.new(pointer))
+				end
+
+				def self.name(kind)
+					Lib.resource_usage_name(kind)
+				end
+
+				def entries
+					ary = []
+					ptr = @resource_usage[:entries]
+					@resource_usage[:numEntries].times {
+						ary << Lib::CXTUResourceUsageEntry.new(ptr)
+						ptr += Lib::CXTUResourceUsageEntry.size
+					}
+					ary
+				end
+			end
+		end
+	end
+end

data/lib/ffi/clang/type.rb

@@ -0,0 +1,135 @@
+# Copyright, 2013, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# Copyright, 2014, by Masahiro Sano.
+# 
+# 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.
+
+require 'ffi/clang/cursor'
+
+module FFI
+	module Clang
+		class Type
+			attr_reader :type
+
+			def initialize(type, translation_unit)
+				@type = type
+				@translation_unit = translation_unit
+			end
+
+			def kind
+				@type[:kind]
+			end
+
+			def kind_spelling
+				Lib.extract_string Lib.get_type_kind_spelling @type[:kind]
+			end
+
+			def spelling
+				Lib.extract_string Lib.get_type_spelling(@type)
+			end
+
+			def variadic?
+				Lib.is_function_type_variadic(@type) != 0
+			end
+
+			def pod?
+				Lib.is_pod_type(@type) != 0
+			end
+
+			def num_arg_types
+				Lib.get_num_arg_types(@type)
+			end
+
+			def pointee
+				Type.new Lib.get_pointee_type(@type), @translation_unit
+			end
+
+			def canonical
+				Type.new Lib.get_canonical_type(@type), @translation_unit
+			end
+
+			def class_type
+				Type.new Lib.type_get_class_type(@type), @translation_unit
+			end
+
+			def const_qualified?
+				Lib.is_const_qualified_type(@type) != 0
+			end
+
+			def volatile_qualified?
+				Lib.is_volatile_qualified_type(@type) != 0
+			end
+
+			def restrict_qualified?
+				Lib.is_restrict_qualified_type(@type) != 0
+			end
+
+			def arg_type(i)
+				Type.new Lib.get_arg_type(@type, i), @translation_unit
+			end
+
+			def result_type
+				Type.new Lib.get_result_type(@type), @translation_unit
+			end
+
+			def element_type
+				Type.new Lib.get_element_type(@type), @translation_unit
+			end
+
+			def num_elements
+				Lib.get_num_elements(@type)
+			end
+
+			def array_element_type
+				Type.new Lib.get_array_element_type(@type), @translation_unit
+			end
+
+			def array_size
+				Lib.get_array_size(@type)
+			end
+
+			def alignof
+				Lib.type_get_align_of(@type)
+			end
+
+			def sizeof
+				Lib.type_get_size_of(@type)
+			end
+
+			def offsetof(field)
+				Lib.type_get_offset_of(@type, field)
+			end
+
+			def ref_qualifier
+				Lib.type_get_cxx_ref_qualifier(@type)
+			end
+
+			def calling_conv
+				Lib.get_fuction_type_calling_conv(@type)
+			end
+
+			def declaration
+				Cursor.new Lib.get_type_declaration(@type), @translation_unit
+			end
+
+			def ==(other)
+				Lib.equal_types(@type, other.type) != 0
+			end
+		end
+	end
+end

data/lib/ffi/clang/unsaved_file.rb

@@ -0,0 +1,49 @@
+# -*- coding: utf-8 -*-
+# Copyright, 2013, by Carlos Martín Nieto <cmn@dwim.me.
+# 
+# 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.
+
+module FFI
+	module Clang
+		class UnsavedFile
+			def initialize(filename, contents)
+				@filename = filename
+				@contents = contents
+			end
+
+			attr_accessor :filename, :contents
+
+
+			def self.unsaved_pointer_from(unsaved)
+				return nil if unsaved.length == 0
+
+				vec = MemoryPointer.new(Lib::CXUnsavedFile, unsaved.length)
+
+				unsaved.each_with_index do |file, i|
+					uf = Lib::CXUnsavedFile.new(vec + i * Lib::CXUnsavedFile.size)
+					uf[:filename] = MemoryPointer.from_string(file.filename)
+					uf[:contents] = MemoryPointer.from_string(file.contents)
+					uf[:length] = file.contents.length
+				end
+
+				vec
+			end
+		end
+	end
+end

data/lib/ffi/clang/utils.rb

@@ -0,0 +1,58 @@
+# Copyright, 2014 by Masahiro Sano.
+# 
+# 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.
+
+require 'ffi/clang/lib/utils'
+require 'ffi/clang/lib/string'
+
+module FFI
+	module Clang
+		class Utils
+			def self.clang_version_string
+				Lib.extract_string Lib.get_clang_version
+			end
+
+			def self.clang_version
+				version = clang_version_string
+				version.match(/based on LLVM (\d+\.\d+)/).values_at(1).first
+			end
+
+			def self.clang_version_symbol
+				version = "clang_" + clang_version.tr('.', '_')
+				version.intern
+			end
+
+			def self.clang_major_version
+				version = clang_version_string
+				version.match(/based on LLVM (\d+)\./).values_at(1).first.to_i
+			end
+
+			def self.clang_minor_version
+				version = clang_version_string
+				version.match(/based on LLVM \d+\.(\d+)/).values_at(1).first.to_i
+			end
+
+			def self.satisfy_version?(min_version, max_version = nil)
+				Gem::Version.create(self.clang_version) >= Gem::Version.create(min_version) and
+					(max_version.nil? or
+					Gem::Version.create(self.clang_version) <= Gem::Version.create(max_version))
+			end
+		end
+	end
+end

data/lib/ffi/clang/version.rb

@@ -0,0 +1,26 @@
+# Copyright, 2010-2012 by Jari Bakken.
+# Copyright, 2013, by Samuel G. D. Williams. <http://www.codeotaku.com>
+# 
+# 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.
+
+module FFI
+	module Clang
+		VERSION = "0.2.0.1"
+	end
+end

data/spec/clang/comment_spec.rb

@@ -0,0 +1,470 @@
+# -*- coding: utf-8 -*-
+# Copyright, 2013, by Carlos Martín Nieto <cmn@dwim.me>
+# 
+# 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.
+
+require 'spec_helper'
+
+describe Comment do
+	let(:cursor) { Index.new.parse_translation_unit(fixture_path("docs.cc")).cursor }
+	let (:comment) { find_first(cursor, :cursor_function).comment }
+
+	it "can be obtained from a cursor" do
+		comment.should be_kind_of(Comment)
+		comment.should be_kind_of(FullComment)
+		comment.kind.should equal(:comment_full)
+	end
+
+	it "can parse the brief description" do
+		para = comment.child
+		para.kind.should equal(:comment_paragraph)
+		para.should be_kind_of(ParagraphComment)
+		text = para.child
+		text.kind.should equal(:comment_text)
+		text.should be_kind_of(TextComment)
+		text.text.strip.should eq("Short explanation")
+	end
+
+	it "can parse the longer description" do
+		para = comment.child(1)
+		para.kind.should equal(:comment_paragraph)
+		para.num_children.should equal(2)
+		text = para.child
+
+		lines = (0..para.num_children-1).map do |i|
+			para.child(i).text
+		end
+
+		lines.should eq([" This is a longer explanation",
+				 " that spans multiple lines"])
+	end
+
+	it "has working helpers" do
+		comment.num_children.should equal(8)
+
+		para = comment.child(1)
+		para.text.should eq(" This is a longer explanation\n that spans multiple lines")
+	end
+
+	it "understands params" do
+		[['input', " some input\n "], ['flags', " some flags\n "]].each_with_index do |v, child_idx|
+			param = comment.child(3 + child_idx)
+			param.should be_kind_of(ParamCommandComment)
+
+			param.valid_index?.should == true
+			param.index.should equal(child_idx)
+			param.name.should eq(v[0])
+			param.child.text.should eq v[1]
+			param.comment.should eq v[1]
+		end
+	end
+
+	describe "#whitespace?" do
+		it "checks the comment is whitespace" do
+			expect(comment.child.whitespace?).to be_false
+		end
+	end
+
+	describe "#has_trailing_newline?" do
+		it "checks the content has a traling newline" do
+			expect(comment.child.has_trailing_newline?).to be_false
+		end
+	end
+
+	context 'comment_null' do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'no_comment_function' } }
+		let(:comment) { comment_cursor.comment }
+
+		it "is null comment" do
+			expect(comment).to be_kind_of(Comment)
+			expect(comment.kind).to eq(:comment_null)
+			expect(comment.text).to eq('')
+		end
+	end
+
+	context 'unknown comment type' do
+		let(:comment) { 'foobar' }
+		it "raises NotImplementedError" do
+			expect(Lib).to receive(:comment_get_kind).with(comment).and_return(:xxx_yyy_zzzz)
+			expect{Comment.build_from(comment)}.to raise_error(NotImplementedError)
+		end
+	end
+
+	describe HTMLStartTagComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'b_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:paragraph) { comment_cursor.comment.child }
+		let(:html_start_tag_comments) { paragraph.children.select{|c| c.kind == :comment_html_start_tag} }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(paragraph).to be_kind_of(ParagraphComment)
+			expect(html_start_tag_comments.first).to be_kind_of(HTMLStartTagComment)
+			expect(html_start_tag_comments.size).to eq(2)
+		end
+
+		describe "#tag" do
+			it "returns HTML tag name" do
+				expect(html_start_tag_comments[0].tag).to eq('br')
+				expect(html_start_tag_comments[1].tag).to eq('a')
+			end
+
+			it "is alias method of #name" do
+				expect(html_start_tag_comments[0].name).to eq('br')
+				expect(html_start_tag_comments[1].name).to eq('a')
+			end
+		end
+
+		describe "#text" do
+			it "returns HTML tag as string", from_3_4: true do
+				expect(html_start_tag_comments[0].text.strip).to eq('<br/>')
+				expect(html_start_tag_comments[1].text.strip).to eq('<a href="http://example.org/">')
+			end
+
+			it "returuns empty string", upto_3_3: true do
+				expect(html_start_tag_comments[0].text.strip).to eq('')
+				expect(html_start_tag_comments[1].text.strip).to eq('')
+			end
+		end
+
+		describe "#self_closing?" do
+			it "checks the tag is self-closing" do
+				expect(html_start_tag_comments[0].self_closing?).to be_true
+				expect(html_start_tag_comments[1].self_closing?).to be_false
+			end
+		end
+
+		describe "#num_attrs" do
+			it "returns the number of attributes" do
+				expect(html_start_tag_comments[0].num_attrs).to eq(0)
+				expect(html_start_tag_comments[1].num_attrs).to eq(1)
+			end
+		end
+
+		describe "#attrs" do
+			it "returns attributes as Array of Hash" do
+				expect(html_start_tag_comments[0].attrs).to eq([])
+                expect(html_start_tag_comments[1].attrs).to eq([{name: 'href', value: 'http://example.org/'}])
+			end
+		end
+	end
+
+	describe HTMLEndTagComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'b_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:paragraph) { comment_cursor.comment.child }
+		let(:html_end_tag_comment) { paragraph.children.select{|c| c.kind == :comment_html_end_tag}.first }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(paragraph).to be_kind_of(ParagraphComment)
+			expect(html_end_tag_comment).to be_kind_of(HTMLEndTagComment)
+		end
+
+		describe "#tag" do
+			it "returns HTML tag name" do
+				expect(html_end_tag_comment.tag).to eq('a')
+			end
+
+			it "is alias method of #name" do
+				expect(html_end_tag_comment.name).to eq('a')
+			end
+		end
+
+		describe "#text" do
+			it "returns HTML tag as string", from_3_4: true do
+				expect(html_end_tag_comment.text.strip).to eq('</a>')
+			end
+
+			it "returuns empty string", upto_3_3: true do
+				expect(html_end_tag_comment.text.strip).to eq('')
+			end
+		end
+	end
+
+	describe FullComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'f_function' } }
+		let(:comment) { comment_cursor.comment }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+		end
+
+		describe "#to_html" do
+			it "converts a given full parsed comment to an HTML fragment", from_3_4: true do
+				expect(comment.to_html).to be_kind_of(String)
+				expect(comment.to_html).to eq('<p class="para-brief"> this is a function.</p>')
+			end
+
+			it "converts a given full parsed comment to an HTML fragment", upto_3_3: true do
+				expect(comment.to_html).to be_kind_of(String)
+				expect(comment.to_html).to eq('<p class="para-brief"> this is a function. </p>')
+			end
+		end
+
+		describe "#to_xml" do
+			it "converts a given full parsed comment to an XML document" do
+				expect(comment.to_xml).to be_kind_of(String)
+			end
+		end
+	end
+
+	describe BlockCommandComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'f_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:block_cmd_comment) { comment.children.select{|c| c.kind == :comment_block_command}.first }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(block_cmd_comment).to be_kind_of(BlockCommandComment)
+			expect(block_cmd_comment.child).to be_kind_of(ParagraphComment)
+		end
+
+		describe "#name" do
+			it "returns the name of the block command" do
+				expect(block_cmd_comment.name).to eq("brief")
+			end
+		end
+
+		describe "#paragraph" do
+			it "returns the paragraph" do
+				expect(block_cmd_comment.paragraph).to be_kind_of(ParagraphComment)
+			end
+		end
+
+		describe "#num_args" do
+			it "returns the number of word-like arguments" do
+				expect(block_cmd_comment.num_args).to eq(0)
+			end
+		end
+
+		describe "#args" do
+			it "returns word-like arguments" do
+				expect(block_cmd_comment.args).to be_kind_of(Array)
+				expect(block_cmd_comment.args).to eq([])
+			end
+
+			#TODO: needs tests with comments which have arguments
+		end
+
+		describe "#text" do
+			it "returns readble text that includes children's comments" do
+				expect(block_cmd_comment.text).to be_kind_of(String)
+				expect(block_cmd_comment.text.strip).to eq('this is a function.')
+			end
+
+			it "is a alias method of #comment" do
+				expect(block_cmd_comment.comment).to eq(block_cmd_comment.text)
+			end
+		end
+	end
+
+	describe InlineCommandComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'd_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:inline_command_comments) { comment.child.children.select{|c| c.kind == :comment_inline_command} }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(comment.child).to be_kind_of(ParagraphComment)
+			expect(inline_command_comments.size).to eq(2)
+		end
+
+		describe "#name" do
+			it "returns the name of the inline command" do
+				expect(inline_command_comments[0].name).to eq("em")
+				expect(inline_command_comments[1].name).to eq("b")
+			end
+		end
+
+		describe "#render_kind" do
+			it "returns the most appropriate rendering mode" do
+				expect(inline_command_comments[0].render_kind).to eq(:emphasized)
+				expect(inline_command_comments[1].render_kind).to eq(:bold)
+			end
+		end
+
+		describe "#num_args" do
+			it "returns number of command arguments" do
+				expect(inline_command_comments[0].num_args).to eq(1)
+				expect(inline_command_comments[1].num_args).to eq(1)
+			end
+		end
+
+		describe "#args" do
+			it "returns arguments as Array" do
+				expect(inline_command_comments[0].args).to eq(["foo"])
+				expect(inline_command_comments[1].args).to eq(["bar"])
+			end
+		end
+
+		describe "#text" do
+			it "returns readble text" do
+				expect(inline_command_comments[0].text.strip).to eq("foo")
+				expect(inline_command_comments[1].text.strip).to eq("bar")
+			end
+		end
+	end
+
+	describe VerbatimBlockCommandComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'e_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:verb_block_cmd_comment) { comment.children.select{|c| c.kind == :comment_verbatim_block_command}.first }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(verb_block_cmd_comment).to be_kind_of(VerbatimBlockCommandComment)
+		end
+
+		describe "#text" do
+			it "returns readble text" do
+				expect(verb_block_cmd_comment.text).to eq("  foo bar\n  baz")
+			end
+		end
+	end
+
+	describe VerbatimBlockLineComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'e_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:verb_block_cmd_comment) { comment.children.select{|c| c.kind == :comment_verbatim_block_command}.first }
+		let(:verb_block_line_comments) { verb_block_cmd_comment.children }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(verb_block_cmd_comment).to be_kind_of(VerbatimBlockCommandComment)
+			expect(verb_block_line_comments.first).to be_kind_of(VerbatimBlockLineComment)
+			expect(verb_block_line_comments.size).to eq(2)
+		end
+
+		describe "#text" do
+			it "returns readble text" do
+				expect(verb_block_line_comments[0].text.strip).to eq("foo bar")
+				expect(verb_block_line_comments[1].text.strip).to eq("baz")
+			end
+		end
+	end
+
+	describe VerbatimLine do
+	# TODO: how to generate this comment?
+	end
+
+	describe ParamCommandComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function and child.spelling == 'a_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:param_cmd_comments) { comment.children.select{|c| c.kind == :comment_param_command} }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(param_cmd_comments.first).to be_kind_of(ParamCommandComment)
+			expect(param_cmd_comments.size).to eq(4)
+		end
+
+		describe "#text" do
+			it "returns readble text" do
+				expect(param_cmd_comments[0].text.strip).to eq("some input")
+				expect(param_cmd_comments[1].text.strip).to eq("some flags")
+			end
+		end
+
+		describe "#direction_explicit?" do
+			it "checks the direction is specified explicitly" do
+				expect(param_cmd_comments[0].direction_explicit?).to be_true
+				expect(param_cmd_comments[3].direction_explicit?).to be_false
+			end
+		end
+
+		describe "#direction" do
+			it "returns parameter passing direction" do
+				expect(param_cmd_comments[0].direction).to eq(:pass_direction_in)
+				expect(param_cmd_comments[1].direction).to eq(:pass_direction_out)
+				expect(param_cmd_comments[2].direction).to eq(:pass_direction_inout)
+				expect(param_cmd_comments[3].direction).to eq(:pass_direction_in)
+			end
+		end
+	end
+
+	describe TParamCommandComment do
+		let(:comment_cursor) { find_matching(cursor) { |child, parent|
+				child.kind == :cursor_function_template and child.spelling == 'c_function' } }
+		let(:comment) { comment_cursor.comment }
+		let(:tparam_cmd_comments) { comment.children.select{|c| c.kind == :comment_tparam_command} }
+
+		it "can be obtained from cursor" do
+			expect(comment).to be_kind_of(FullComment)
+			expect(comment.kind).to equal(:comment_full)
+			expect(tparam_cmd_comments.first).to be_kind_of(TParamCommandComment)
+			expect(tparam_cmd_comments.size).to eq(3)
+		end
+
+		describe "#text" do
+			it "returns readble text" do
+				expect(tparam_cmd_comments[0].text.strip).to eq("some type of foo")
+				expect(tparam_cmd_comments[1].text.strip).to eq("some type of bar")
+			end
+		end
+
+		describe "#name" do
+			it "returns template parameter name" do
+				expect(tparam_cmd_comments[0].name).to eq("T1")
+				expect(tparam_cmd_comments[1].name).to eq("T2")
+				expect(tparam_cmd_comments[2].name).to eq("T3")
+			end
+		end
+
+		describe "#valid_position?" do
+			it "checks this parameter has valid position" do
+				expect(tparam_cmd_comments[0].valid_position?).to be_true
+			end
+		end
+
+		describe "#depth" do
+			it "returns nesting depth of this parameter" do
+				expect(tparam_cmd_comments[0].depth).to eq(1)
+				expect(tparam_cmd_comments[1].depth).to eq(2)
+				expect(tparam_cmd_comments[2].depth).to eq(1)
+			end
+		end
+
+		describe "#index" do
+			it "returns index of the parameter at the given nesting depth" do
+				expect(tparam_cmd_comments[0].index(0)).to eq(0)
+				expect(tparam_cmd_comments[1].index(0)).to eq(1)
+				expect(tparam_cmd_comments[1].index(1)).to eq(0)
+				expect(tparam_cmd_comments[2].index(0)).to eq(1)
+			end
+		end
+	end
+end