rdx 0.9.0.pre

data/lib/rdx/generator.rb

@@ -0,0 +1,112 @@
+
+module RDX
+	
+	#
+	# RDX doesn't have its own parser, formatting rules and templates for generating
+	# documentation from the source files. Instead, it does rely on tools already existing.
+	# Such tools are wrapped by subclasses of RDX::Generator, in order to provide a common
+	# interface to the outside world. Those need very likely to be patched
+	# (allowing to interact with RDX and work properly).
+	# 
+	# Currently only RDoc is supported (see Generator::RDoc),
+	# but YARD will probably be the next one on the list.
+	#
+	class Generator
+		
+	# :stopdoc:
+		
+		@generators = {}
+		class << self
+			attr_reader :generators
+		end
+		def self.generator_name
+			name.split('::').last.downcase
+		end
+		def self.inherited child_class
+			Generator.generators[child_class.generator_name] = child_class
+		end
+		def self.[] name
+			name = name.downcase
+			require "rdx/generator/#{name}"
+			Generator.generators[name]
+		end
+		
+		@current = nil
+		class << self
+			attr_accessor :current
+		end
+		
+		def name
+			self.class.generator_name
+		end
+		
+		attr_reader :options
+		
+		def initialize
+			@options = {}
+		end
+		
+	# :startdoc:
+		
+		# Additional options for the generator.
+		def custom_options
+			[]
+		end
+		
+		#
+		# Merges the given _argv_ and _files_ (along with #custom_options)
+		# into a ingle +Array+ of options.
+		#
+		def merge_argv_and_files argv, files
+			custom_options + argv + ['--'] + files
+		end
+		
+		# Sets up <tt>Generator.current</tt>, and relies to #document.
+		def generate argv=[], files=[]
+			Generator.current = self
+			argv = merge_argv_and_files argv, files
+			document argv
+		ensure
+			Generator.current = nil
+		end
+		
+		#
+		# The generator should implement this method in order to produce documentation output from _argv_
+		# (command line options).
+		#
+		def document argv=[]
+		end
+		
+		#
+		# The generator should implement this method in order to recognize the directives.
+		# The result should be a +Regexp+ with two capturing groups: the directive name and
+		# its parameter.
+		#
+		def directive_rgxp
+		end
+			
+		#
+		# The generator should implement this method in order to recognize the example sections
+		# from _text_.
+		# The result should be an +Array+ <tt>[ [text,line_no],... ]</tt>
+		#
+		def recognize_examples text
+			vbs = ::RDoc::Markup::Parser.get_verbatims(text)
+			vbs.map{ |vb| [vb.text,vb.line_no] }
+		end
+		
+		#
+		# The generator should implement this method in order to customize the template
+		# with the RDX signature.
+		#
+		def customize_template template_string
+		end
+		
+		def RDX.customize_template template # :nodoc:
+			return template unless passed?
+			generator.customize_template template
+		end
+		
+	end
+	
+end

data/lib/rdx/generator/rdoc.rb

@@ -0,0 +1,1006 @@
+
+require 'rdoc'
+
+#
+# :rdx: off
+# 
+# This patch handles specific issues and comunication of RDoc with RDX, allowing it to work properly.
+# There are a few important thing to notify.
+# 
+# == Private RDX sections
+# 
+# RDoc already allows private comments (both for C and Ruby files):
+# sections between <tt>--</tt> and <tt>++</tt> (at the beginning of the line)
+# are removed from documentation.
+# 
+# If a line of comment begins with <tt>-- rdx</tt> that section is
+# removed from documentation, but kept for RDX processing:
+# in this way we can embed additional code, for example to hide
+# additional details or to do some sort of clean-up.
+# 
+# An example (from <tt>numeric.c</tt>):
+# 
+#   /*
+#    *  [...]
+#    *-- rdx
+#    *  It's clear from the examples that x and y are generical...
+#    *     x = (-1)**rand(2) * (1+rand(10)*1.5)
+#    *     y = (-1)**rand(2) * (1+rand(10)*1.5)
+#    *++
+#    *  The <code>modulo</code> is defined as:
+#    *     x.modulo(y) #=> x-y*(x/y).floor
+#    *  [...]
+#    */
+#   static VALUE
+#   num_modulo(VALUE x, VALUE y)
+# 
+# == Directives
+#--
+# TODO: Probably move some documentation to +Generator+.
+#++
+#
+# RDoc directives are keywords surrounded by ":" characters,
+# and what follows is its parameter:
+# 
+#   \:rdoc_directive: rdoc_parameter
+# 
+# To insert a directive for RDX first we have to tell this to RDoc using +rdx+
+# as the _rdoc_directive_.
+# Then the _rdoc_parameter_ is parsed by RDX (specifically by RDX::Directive.split)
+# and split into an RDX directive name and its parameter.
+# 
+# Indeed the whole sequence in a comment looks like this:
+# 
+#   \:rdx: rdx_directive_name rdx_directive_parameter
+#   
+# For example:
+# 
+#   # Sorts a collection in descending order.
+#   # :rdx: skip write an example
+#   def reverse_sort enum
+#     enum.sort.reverse
+#   end
+#   
+# Here the RDX's directive name is +skip+ (which corresponds to RDX::Directive::skip)
+# and its parameter is the +String+ <tt>"write an example"</tt>.
+# 
+# To known the available directives in RDX and the parameter they support,
+# consult the RDX::Directive class.
+# 
+# This patch also removes from RDoc the <tt>:rdx:</tt> directive,
+# so that they won't be shown in the documentation output
+# (this happens before examples are recognized, so the indentation of directives
+# has no effect on the rest of comment).
+# 
+# == Visibility of comments
+# 
+# While the generator scans the source files some comments are kept for the documentation
+# output, others are discarded, others may even be not seen.
+# 
+# The last type ones (_missed_ comments) don't even sprung into existence.
+# Conversely the other two types can generate RDX::Comment objects.
+# What discriminates them is the +documenting+ attribute:
+# for this reason we refer to them with _documenting_ and _non_documenting_ comments.
+# 
+# Since RDoc can fully tokenize Ruby files but not C ones
+# it can see all Ruby comments but only "useful" C comments are recognized.
+# This means that _missed_ C comments exist, while Ruby ones do not.
+# 
+# A _non_documenting_ comment may generate warnings -
+# for example if a convention is recognized inside it:
+# 
+#   # Documenting comment
+#   #   return_one #=> 1
+#   def return_one
+#     1
+#   end
+#   
+#   # :stopdoc:
+#   
+#   # ... many lines of code ...
+#   
+#   # Non-documenting comment
+#   #   return_two #=> 2
+#   def return_two
+#     2
+#   end
+#   
+# A _missed_ one surely cannot, so be careful.
+#
+module RDoc; end
+
+module RDoc # :nodoc: all
+	
+	class << Encoding # :nodoc: all
+		
+		alias set_encoding_consume_nl set_encoding
+		private :set_encoding_consume_nl
+		# EDIT: Don't consume the first newline character when changing the encoding.
+		def set_encoding string
+			orig_size = string.size
+			result = set_encoding_consume_nl(string)
+			return result if string.size == orig_size # No encode changing
+			string.sub!(/\A(#!.*\n)?/,"\\1\n") # Add the removed newline after the shebang line (if present)
+			result
+		end
+		
+	end
+	
+	module Text
+		
+		require 'rdx/text'
+		
+		# Remove stars only if it's a full C-commment: containing it isn't enough.
+		define_method :strip_stars, &RDX::Text.method(:strip_stars)
+		
+	end
+	
+	class Comment
+		
+		# The associated comment in RDX (or +nil+ if there isn't).
+		attr_reader :rdx_comment
+		
+		def rdx_line_no= line_no
+			return unless rdx_comment
+			rdx_comment.line_no = line_no
+		end
+		
+		def rdx_file_name= file_name
+			return unless rdx_comment
+			rdx_comment.file_name = file_name
+		end
+		
+		def rdx_mark_doc(parent_comment=nil)
+			return unless rdx_comment
+			rdx_comment.documenting = true
+			return if parent_comment.nil?
+			rdx_comment.enclosing_comment = parent_comment.rdx_comment
+		end
+		
+		def absolute_location
+			root = RDoc.current.options.root
+			File.expand_path(location.absolute_name,root.dirname)
+		end
+		
+		alias initialize_wo_rdx initialize
+		private :initialize_wo_rdx
+		# Add logging for line number and RDX lines
+		def initialize(*args,&blk)
+			result = initialize_wo_rdx(*args,&blk)
+			@private_removed = false
+			if RDX.active? && location && !text.empty?
+				@rdx_comment = RDX::Comment.new(text.dup,absolute_location,nil)
+			end
+			remove_rdx_directives
+			result
+		end
+		
+		def remove_rdx_directives
+			text.gsub! %r%^
+				(
+					[^\S\n]*
+					(?: [#*] [^\S\n]* )?
+				)
+				:rdx: .*
+			%x, '\1'
+		end
+		private :remove_rdx_directives
+		
+		#
+		# Remove private sections keeping newlines characters from +rdx_comment+.
+		#--
+		# Method adapted from RDoc::Comment#remove_private
+		#
+		def rdx_remove_private
+			return unless rdx_comment
+			
+		# From RDoc:
+		#	# Workaround for gsub encoding for Ruby 1.9.2 and earlier
+		#	empty = ''
+		#	empty.force_encoding @rdx_text.encoding if Object.const_defined? :Encoding
+		#
+		#	@text = @text.gsub(%r%^\s*([#*]?)--.*?^\s*(\1)\+\+\n?%m, empty)
+		#	@text = @text.sub(%r%^\s*[#*]?--.*%m, '')
+		#	return self
+		
+			text = rdx_comment.text
+			
+			text.gsub! %r%
+				^ ( (?:[^\S\n]*[#*])? )   # \1: delimiter
+					-- (.* \n)              # \2: private header
+				( (?> .* \n )*? )         # \3: body
+				\1 \+\+ \n?
+			%x do |txt|
+				delimiter,header,body = Regexp.last_match.captures
+				if header[/^\s*rdx\s/i]
+					"#{delimiter}\n" + body + "#{delimiter}\n"
+				else
+					RDX::Text.collect_newlines(txt,delimiter)
+				end
+			end
+			
+			text.sub! %r%
+				^ ( (?:[^\S\n]*[#*])? )   # captures as above
+					-- (.* \n)
+				( (?m:.*) )
+			%x do |txt|
+				delimiter,header,body = Regexp.last_match.captures
+				if header[/^\s*rdx\s/i]
+					"#{delimiter}\n" + body
+				else
+					RDX::Text.collect_newlines(txt,delimiter)
+				end
+			end
+			return self
+		end
+		
+		alias remove_private_wo_rdx remove_private
+		private :rdx_remove_private, :remove_private_wo_rdx
+		def remove_private(*args,&blk)
+			unless @private_removed
+				remove_private_wo_rdx(*args,&blk)
+				rdx_remove_private
+				@private_removed = true
+			end
+			return self
+		end
+		
+		def rdx_normalize
+			return unless rdx_comment
+			rdx_comment.normalize
+		end
+		alias normalize_wo_rdx normalize
+		private :rdx_normalize, :normalize_wo_rdx
+		#
+		# INSERTION: Normalize also the corresponding comment in RDX.
+		#
+		def normalize(*args,&blk)
+			remove_private # we want to be sure that it occurs for every comment that has to be normalized
+			r = normalize_wo_rdx(*args,&blk)
+			rdx_normalize
+			r
+		end
+		
+		#
+		# Extracts 'call-seq' directive keeping newlines characters from +rdx_comment+.
+		#--
+		# Method adapted from RDoc::Comment#extract_call_seq
+		#
+		def rdx_extract_call_seq
+			return unless rdx_comment
+			text = rdx_comment.text
+			# we must handle situations like the above followed by an unindented first
+			# comment.  The difficulty is to make sure not to match lines starting
+			# with ARGF at the same indent, but that are after the first description
+			# paragraph.
+			if text =~ /^\s*:?call-seq:(.*?(?:\S).*?)^\s*$/m then
+				all_start, all_stop = $~.offset(0)
+				seq_start, seq_stop = $~.offset(1)
+
+				# we get the following lines that start with the leading word at the
+				# same indent, even if they have blank lines before
+				if $1 =~ /(^\s*\n)+^(\s*\w+)/m then
+					leading = $2 # ' *    ARGF' in the example above
+					re = %r%
+						\A(
+							 (^\s*\n)+
+							 (^#{Regexp.escape leading}.*?\n)+
+							)+
+						^\s*$
+					%xm
+
+					if text[seq_stop..-1] =~ re then
+						all_stop = seq_stop + $~.offset(0).last
+						seq_stop = seq_stop + $~.offset(1).last
+					end
+				end
+
+		#		seq = text[seq_start..seq_stop]
+		#		seq.gsub!(/^\s*(\S|\n)/m, '\1')
+		#		@text.slice! all_start...all_stop
+				text[all_start...all_stop] = RDX::Text.collect_newlines(text[all_start...all_stop])
+		#		method.call_seq = seq.chomp
+
+		#	elsif @text.sub!(/^\s*:?call-seq:(.*?)(^\s*$|\z)/m, '') then
+			elsif text.sub!(/^\s*:?call-seq:(.*?)(^\s*$|\z)/m){ |s| RDX::Text.collect_newlines(s) } then
+		#		seq = $1
+		#		seq.gsub!(/^\s*/, '')
+		#		method.call_seq = seq
+			
+		# Single line directives has alredy been removed
+		#	#elsif @text.sub!(/\A\/\*\s*call-seq:(.*?)\*\/\Z/, '') then
+		#	#  method.call_seq = $1.strip
+			
+			end
+			
+			# The :call-seq: isn't part of the plain text, which is next to the left margin
+			text.replace RDX::Text.flush_left(text)
+
+		#	method
+			self
+		end
+		alias extract_call_seq_wo_rdx extract_call_seq
+		private :rdx_extract_call_seq, :extract_call_seq_wo_rdx
+		#
+		# Remove also +call_seq+ information from RDX's comment.
+		#
+		def extract_call_seq(*args,&blk)
+			r = extract_call_seq_wo_rdx(*args,&blk)
+			rdx_extract_call_seq
+			r
+		end
+		
+	end
+	
+	class Store
+		
+		attr_reader :rdx_code_objects
+		
+		alias initialize_wo_rdx initialize
+		private :initialize_wo_rdx
+		def initialize(*args,&blk)
+			@rdx_code_objects = []
+			initialize_wo_rdx(*args,&blk)
+		end
+		
+	end
+	
+	class CodeObject
+		
+		alias set_store_wo_rdx store=
+		private :set_store_wo_rdx
+		#
+		# This method is called for those and only objects whose will appear in documentation,
+		# so we can hook into and register these objects for RDX
+		#
+		def store=(*args,&blk)
+			rs = set_store_wo_rdx(*args,&blk)
+			store.rdx_code_objects << self
+			rs
+		end
+		
+		def rdx_parent
+			parent if parent.is_a?(ClassModule) # Discard top-level (file) comments
+		end
+		
+		#
+		# Shorthand used by rdx
+		#
+		def rdx_comments
+			result = if respond_to?(:comment_location)
+				comment_location.map(&:first)
+			else
+				[comment]
+			end
+			result.grep(Comment) # remove strings (empty)
+		end
+		
+		def rdx_mark_doc
+			rdx_comments.each do |comment|
+				location = comment.location
+				parent_comments = rdx_parent ? rdx_parent.rdx_comments : []
+				parent_comment = parent_comments.find do |cmt|
+					cmt.location == location
+				end
+				comment.rdx_mark_doc(parent_comment)
+			end
+		end
+		
+	end
+	
+	class Parser::Simple
+		
+		PRV_CMT_RDX_HEADER = /[^\S\n]* rdx [^\S\n]*/i
+		
+		alias scan_wo_rdx scan
+		private :scan_wo_rdx
+		def scan(*args,&blk)
+			result = scan_wo_rdx(*args,&blk)
+			# private sections removed through #remove_private_comment and #rdx_remove_private
+			@top_level.comment.instance_variable_set :@private_removed, true
+			rdx_process_comment @top_level.comment.rdx_comment
+			result
+		end
+		
+	private
+
+		def remove_private_comment comment
+			# Workaround for gsub encoding for Ruby 1.9.2 and earlier
+#			empty = ''
+#			empty.force_encoding comment.encoding if Object.const_defined? :Encoding
+			comment = comment.gsub %r%^--#{PRV_CMT_RDX_HEADER}?\n.*?^\+\+\n?%mo do |txt|
+				RDX::Text.collect_newlines txt
+			end
+			comment.sub! %r%^--#{PRV_CMT_RDX_HEADER}?\n.*%mo do |txt|
+				RDX::Text.collect_newlines txt
+			end
+			comment
+		end
+
+		def rdx_process_comment comment
+			return unless comment
+			comment.line_no = 1
+			comment.documenting = true
+			comment.text = rdx_remove_private comment.text
+		end
+		
+		def rdx_remove_private text
+		#	# Workaround for gsub encoding for Ruby 1.9.2 and earlier
+		#	empty = ''
+		#	empty.force_encoding comment.encoding if Object.const_defined? :Encoding
+		#	text = text.gsub(%r%^--\n.*?^\+\+\n?%im, empty)
+		#	text.sub(%r%^--\n.*%m, empty)
+
+			text.gsub! %r%
+				^ ( (?:[^\S\n]*[#*])? )              # \1: comment delimiter
+					-- (#{PRV_CMT_RDX_HEADER})? \n     # \2: rdx header - optional
+				( (?> .* \n )*? )                    # \3: body
+				\1 \+\+ \n?
+			%xo do |txt|
+				delimiter,header,body = Regexp.last_match.captures
+				if header
+					"#{delimiter}\n" + body + "#{delimiter}\n"
+				else
+					RDX::Text.collect_newlines(txt,delimiter)
+				end
+			end
+			
+			text.sub! %r%
+				^ ( (?:[^\S\n]*[#*])? )              # captures as above
+					-- (#{PRV_CMT_RDX_HEADER})? \n
+				( (?m:.*) )
+			%xo do |txt|
+				delimiter,header,body = Regexp.last_match.captures
+				if header
+					"#{delimiter}\n" + body
+				else
+					RDX::Text.collect_newlines(txt,delimiter)
+				end
+			end
+			
+			text
+		end
+		
+	end
+	
+	#
+	# Some method has been rewritten in order to keep track and add line numbers for parsed comments.
+	#
+	class Parser::Ruby
+		
+		alias get_tk_wo_line_no get_tk
+		private :get_tk_wo_line_no
+		#
+		# Keep the line number when a comment is found.
+		#--
+		# Hack RDoc::RubyLex#identify_comment instead (but allow multiline)
+		#
+		def get_tk
+			tk = get_tk_wo_line_no
+			return tk unless RDX.active?
+			@current_tk_comment_line_no ||= tk.line_no if tk.is_a?(TkCOMMENT)
+			tk
+		end
+		
+		alias new_comment_wo_line_no new_comment
+		private :new_comment_wo_line_no
+		#
+		# Create the comment with the cached line number and clear cache.
+		#
+		def new_comment(*args,&blk)
+			cmt = new_comment_wo_line_no(*args,&blk)
+			if @current_tk_comment_line_no
+				cmt.rdx_line_no = @current_tk_comment_line_no
+				@current_tk_comment_line_no = nil
+			end
+			cmt
+		end
+		
+		# Delete the cached line number for the first comment if it's an interpreter directive (#!)
+		# or an ERB directive (# -*-).
+		# In this case we are allowed to skip newlines, otherwise we cannot.
+		alias collect_first_comment_wo_rdx collect_first_comment
+		def collect_first_comment
+			return collect_first_comment_wo_rdx unless RDX.active?
+			skip_tkspace
+			comment = ''
+			comment.force_encoding @encoding if @encoding
+			first_line = true
+
+			tk = get_tk
+
+			while TkCOMMENT === tk
+				if first_line and tk.text =~ /\A#!/ then
+					@current_tk_comment_line_no = nil # <--- line added for RDX
+					skip_tkspace
+					tk = get_tk
+				elsif first_line and tk.text =~ /\A#\s*-\*-/ then
+					first_line = false
+					@current_tk_comment_line_no = nil # <--- line added for RDX
+					skip_tkspace
+					tk = get_tk
+				else
+					first_line = false
+					comment << tk.text << "\n"
+					tk = get_tk
+
+					if TkNL === tk then
+						skip_tkspace false
+						tk = get_tk
+					end
+				end
+			end
+
+			unget_tk tk
+
+			new_comment comment
+		end
+
+	end
+	
+	#
+	class Parser::C
+		
+		def find_rdx_comments
+			@content.scan %r%
+				^ \s* /\*
+					[^\S\n]* :rdx: .*?
+				\*/
+			%imx do |comment|
+				md = Regexp.last_match
+				cmt = Comment.new comment, @top_level
+				cmt.rdx_line_no = md.pre_match.count("\n") + 1
+			end
+		end
+		private :find_rdx_comments
+		
+		alias initialize_wo_rdx initialize
+		private :initialize_wo_rdx
+		def initialize(*args,&blk)
+			r = initialize_wo_rdx(*args,&blk)
+			find_rdx_comments if RDX.active?
+			r
+		end
+		
+		#
+		# Remove \#ifdefs but keep newlines
+		#
+		def handle_ifdefs_in(body)
+			body.gsub /^#ifdef HAVE_PROTOTYPES.*?#else.*?\n(.*?)#endif.*?\n/m do |text|
+				md = Regexp.last_match
+				pre_text = text[0 ... md.begin(1)-md.begin(0)]
+				post_text = text[md.end(1)-md.begin(0) .. -1]
+				pre  = RDX::Text.collect_newlines( pre_text )
+				cnt  = md[1]
+				post = RDX::Text.collect_newlines( post_text )
+				pre + cnt + post
+			end
+		end
+		
+		def find_alias_comment class_name, new_name, old_name
+			content =~ %r%((?>/\*.*?\*/\s+))
+										rb_define_alias\(\s*#{Regexp.escape class_name}\s*,
+																		 \s*"#{Regexp.escape new_name}"\s*,
+																		 \s*"#{Regexp.escape old_name}"\s*\);%xm
+
+			cmt = Comment.new($1 || '', @top_level)
+			cmt.rdx_line_no = $`.count("\n") + 1 if $`
+			cmt
+		end
+		
+		def find_attr_comment var_name, attr_name, read = nil, write = nil
+			attr_name = Regexp.escape attr_name
+
+			rw = if read and write then
+						 /\s*#{read}\s*,\s*#{write}\s*/xm
+					 else
+						 /.*?/m
+					 end
+
+			comment = if @content =~ %r%((?>/\*.*?\*/\s+))
+																	rb_define_attr\((?:\s*#{var_name},)?\s*
+																									"#{attr_name}"\s*,
+																									#{rw}\)\s*;%xm then
+									$1
+								elsif @content =~ %r%((?>/\*.*?\*/\s+))
+																		 rb_attr\(\s*#{var_name}\s*,
+																							\s*#{attr_name}\s*,
+																							#{rw},.*?\)\s*;%xm then
+									$1
+								elsif @content =~ %r%Document-attr:\s#{attr_name}\s*?\n
+																		 ((?>.*?\*/))%xm then
+									$1
+								else
+									''
+								end
+
+			cmt = Comment.new comment, @top_level
+			cmt.rdx_line_no = @content[0...$~.begin(1)].count("\n") + 1 unless comment.empty?
+			cmt
+		end
+		
+		alias handle_method_wo_rdx handle_method
+		private :handle_method_wo_rdx
+		def handle_method(*args,&blk)
+			return handle_method_wo_rdx(*args,&blk) unless RDX.active?
+			result = comment = absolute_path = nil
+			RDX::Util.patch_singleton_method ::File, :read,
+				lambda{ |orig_method,file,*args,&blk|
+					f_result = orig_method.call(file,*args,&blk)
+					absolute_path = ::File.expand_path(file)
+					f_result
+			} do
+				RDX::Util.patch_singleton_method Comment, :new,
+					lambda{ |orig_method,*args,&blk|
+						comment = orig_method.call(*args,&blk)
+				} do
+					result = handle_method_wo_rdx(*args,&blk)
+				end
+			end
+			if comment && absolute_path
+				comment.rdx_file_name = absolute_path
+			end
+			result
+		end
+		
+		def find_body class_name, meth_name, meth_obj, file_content, quiet = false
+			case file_content
+			when %r%((?>/\*.*?\*/\s*)?)
+							((?:(?:static|SWIGINTERN)\s+)?
+							 (?:intern\s+)?VALUE\s+#{meth_name}
+							 \s*(\([^)]*\))([^;]|$))%xm then
+				comment = Comment.new $1, @top_level
+				comment.rdx_line_no = $`.count("\n") + 1
+				body = $2
+				offset, = $~.offset(2)
+
+				comment.remove_private if comment
+
+				# try to find the whole body
+				body = $& if /#{Regexp.escape body}[^(]*?\{.*?^\}/m =~ file_content
+
+				# The comment block may have been overridden with a 'Document-method'
+				# block. This happens in the interpreter when multiple methods are
+				# vectored through to the same C method but those methods are logically
+				# distinct (for example Kernel.hash and Kernel.object_id share the same
+				# implementation
+
+				override_comment = find_override_comment class_name, meth_obj
+				comment = override_comment if override_comment
+
+				comment.normalize
+				find_modifiers comment, meth_obj if comment
+
+				#meth_obj.params = params
+				meth_obj.start_collecting_tokens
+				tk = RubyToken::Token.new nil, 1, 1
+				tk.set_text body
+				meth_obj.add_token tk
+				meth_obj.comment = comment
+				meth_obj.offset  = offset
+				meth_obj.line    = file_content[0, offset].count("\n") + 1
+
+				body
+			when %r%((?>/\*.*?\*/\s*))^\s*(\#\s*define\s+#{meth_name}\s+(\w+))%m then
+				comment = Comment.new $1, @top_level
+				comment.rdx_line_no = $`.count("\n") + 1
+				body = $2
+				offset = $~.offset(2).first
+
+				find_body class_name, $3, meth_obj, file_content, true
+
+				comment.normalize
+				find_modifiers comment, meth_obj
+
+				meth_obj.start_collecting_tokens
+				tk = RubyToken::Token.new nil, 1, 1
+				tk.set_text body
+				meth_obj.add_token tk
+				meth_obj.comment = comment
+				meth_obj.offset  = offset
+				meth_obj.line    = file_content[0, offset].count("\n") + 1
+
+				body
+			when %r%^\s*\#\s*define\s+#{meth_name}\s+(\w+)%m then
+				# with no comment we hope the aliased definition has it and use it's
+				# definition
+
+				body = find_body(class_name, $1, meth_obj, file_content, true)
+
+				return body if body
+
+				@options.warn "No definition for #{meth_name}"
+				false
+			else # No body, but might still have an override comment
+				comment = find_override_comment class_name, meth_obj
+
+				if comment then
+					comment.normalize
+					find_modifiers comment, meth_obj
+					meth_obj.comment = comment
+
+					''
+				else
+					@options.warn "No definition for #{meth_name}"
+					false
+				end
+			end
+		end
+		
+		#
+		# Add line number tracking
+		#
+		def find_class_comment class_name, class_mod
+			comment = nil
+
+			if @content =~ %r%
+					((?>/\*.*?\*/\s+))
+					(static\s+)?
+					void\s+
+					Init_#{class_name}\s*(?:_\(\s*)?\(\s*(?:void\s*)?\)%xmi then
+				line_no = $`.count("\n") + 1
+				comment = $1.sub(%r%Document-(?:class|module):\s+#{class_name}%, '')
+			elsif @content =~ %r%Document-(?:class|module):\s+#{class_name}\s*?
+													 (?:<\s+[:,\w]+)?\n((?>.*?\*/))%xm then
+				line_no = @content[0...$~.begin(1)].count("\n")
+				comment = "/*\n#{$1}"
+			elsif @content =~ %r%.*((?>/\*.*?\*/\s+))
+													 ([\w\.\s]+\s* = \s+)?rb_define_(class|module).*?"(#{class_name})"%xm then
+				line_no = @content[0...$~.begin(1)].count("\n") + 1
+				comment = $1
+			elsif @content =~ %r%.*((?>/\*.*?\*/\s+))
+													 ([\w\.\s]+\s* = \s+)?rb_define_(class|module)_under.*?"(#{class_name.split('::').last})"%xm then
+				line_no = @content[0...$~.begin(1)].count("\n") + 1
+				comment = $1
+			else
+				comment = ''
+			end
+
+			comment = Comment.new comment, @top_level
+			comment.rdx_line_no = line_no
+			comment.normalize
+
+			look_for_directives_in class_mod, comment
+
+			class_mod.add_comment comment, @top_level
+		end
+		
+		def find_const_comment(type, const_name, class_name = nil)
+			comment = if @content =~ %r%^\s*((?>/\*.*?\*/))\s+
+															 rb_define_#{type}\((?:\s*(\w+),)?\s*
+																									"#{const_name}"\s*,
+																									.*?\)\s*;%xmi then
+									line_no = @content[0...$~.begin(1)].count("\n") + 1
+									$1
+								elsif class_name and
+											@content =~ %r%Document-(?:const|global|variable):\s
+																		 #{class_name}::#{const_name}
+																		 \s*?\n((?>.*?\*/))%xm then
+									line_no = @content[0...$~.begin(1)].count("\n")
+									"/*\n#{$1}"
+								elsif @content =~ %r%Document-(?:const|global|variable):
+																		 \s#{const_name}
+																		 \s*?\n((?>.*?\*/))%xm then
+									line_no = @content[0...$~.begin(1)].count("\n")
+									"/*\n#{$1}"
+								else
+									''
+								end
+
+			cmt = Comment.new comment, @top_level
+			cmt.rdx_line_no = line_no
+			cmt
+		end
+		
+		def find_override_comment class_name, meth_obj
+			name = Regexp.escape meth_obj.name
+			prefix = Regexp.escape meth_obj.name_prefix
+
+			comment = if @content =~ %r%Document-method:
+																	\s+#{class_name}#{prefix}#{name}
+																	\s*?\n((?>.*?\*/))%xm then
+									"/*\n#{$1}"
+								elsif @content =~ %r%Document-method:
+																		 \s#{name}\s*?\n((?>.*?\*/))%xm then
+									"/*\n#{$1}"
+								end
+
+			return unless comment
+			line_no = @content[0...$~.begin(1)].count("\n")
+
+			comment.gsub!(%r%Document-method:\s+[\w:.#=!?]+%){ |s| RDX::Text.collect_newlines(s) } # <-- moved from RDoc::Text
+			
+			cmt = Comment.new comment, @top_level
+			cmt.rdx_line_no = line_no
+			cmt
+		end
+	
+	end
+	
+	class Markup::Verbatim
+		alias normalize_wo_rdx normalize
+		private :normalize_wo_rdx
+		# Newlines in some cases doesn't have to be collapsed for reason explained in RDoc::Text.
+		# However this isn't the default behaviour
+		def normalize(*args,&blk)
+			return parts if RDX.active?
+			normalize_wo_rdx(*args,&blk)
+		end
+		
+		# relative to the comment
+		attr_accessor :line_no	
+	end
+	
+	class Markup::Parser
+		alias build_verbatim_wo_line_no build_verbatim
+		private :build_verbatim_wo_line_no
+		# Add logging of line number to verbatim sections
+		def build_verbatim(*args,&blk)
+			line_no = @current_token[3] + 1
+			build_verbatim_wo_line_no(*args,&blk).tap{ |vb| vb.line_no = line_no }
+		end
+	end
+
+	class << Markup::Parser # :nodoc: all
+		#
+		# Parses the string _str_ and returns an array of RDoc::Markup::Verbatim, representing the
+		# verbatim sections contained in that string.
+		#
+		def get_verbatims str
+			flatten_parts(parse(str).parts).grep(Markup::Verbatim)
+		end
+	private
+		# Flattens recursively an array of parts into each part's components
+		def flatten_parts(ary)
+			result = []
+			ary.each do |elm|
+				case elm
+				when Markup::List
+					result.concat flatten_parts(elm.items)
+				when Markup::ListItem
+					result.concat flatten_parts(elm.parts)
+				else
+					result << elm
+				end
+			end
+			result
+		end
+	end
+	
+	class Markup::PreProcess
+		
+		alias include_file_wo_rdx include_file
+		private :include_file_wo_rdx
+		def include_file(*args,&blk)
+			return include_file_wo_rdx(*args,&blk) unless RDX.active?
+			absolute_path = nil
+			content = ''
+			RDX::Util.patch_singleton_method Encoding, :read_file,
+				lambda{ |orig_method,file,*args,&blk|
+					result = orig_method.call(file,*args,&blk)
+					absolute_path = File.expand_path(file)
+					content = result.dup
+					result
+			} do
+				result = include_file_wo_rdx(*args,&blk)
+				mark_for_rdx(absolute_path,content)
+				result
+			end
+		end
+		
+	private
+	
+		def mark_for_rdx absolute_path, content
+			# We want to use Comments' method without knowing anything about initialization, location, etc...
+			Comment.allocate.instance_eval do
+				# Hook in RDX::Comment#initialize
+				@rdx_comment = RDX::Comment.new(content,absolute_path,1)
+				@rdx_comment.documenting = true
+				rdx_remove_private
+				@rdx_comment = nil
+			end
+		end
+		
+	end
+
+	class Generator::Darkfish
+		
+		alias assemble_template_wo_rdx assemble_template
+		private :assemble_template_wo_rdx
+		# Add RDX's signature
+		def assemble_template(*args,&blk)
+			RDX.customize_template assemble_template_wo_rdx(*args,&blk)
+		end
+		
+	end
+	
+	class RDoc
+
+		alias document_wo_current_hook document
+		def document(*args,&blk)
+			self.class.current = self
+			document_wo_current_hook(*args,&blk)
+		ensure
+			self.class.current = nil
+		end
+		
+		alias parse_files_wo_rdx parse_files
+		private :parse_files_wo_rdx
+		# SIGNAL INSERTION: Signal RDX the parsing phase.
+		def parse_files(*args,&blk)
+			return parse_files_wo_rdx(*args,&blk) unless RDX.active?
+			RDX.signal_parsing do
+				result = parse_files_wo_rdx(*args,&blk)
+				store.rdx_code_objects.each(&:rdx_mark_doc).clear
+				result
+			end
+		end
+		
+		alias parse_file_wo_rdx parse_file
+		private :parse_file_wo_rdx
+		# SIGNAL INSERTION: Signal RDX the succesful end of parsing a file.
+		def parse_file rel_fname
+			return parse_file_wo_rdx(rel_fname) unless RDX.active?
+			abs_fname = File.expand_path(rel_fname,options.root)
+			RDX.signal_start_parsing_file(abs_fname)
+			parse_file_wo_rdx(rel_fname).tap do |parseable|
+				RDX.signal_end_parsing_file(abs_fname,parseable)
+			end
+		end
+		
+		alias generate_wo_rdx generate
+		private :generate_wo_rdx
+		# SIGNAL INSERTION: Signal RDX the generating phase.
+		def generate(*args,&blk)
+			return generate_wo_rdx(*args,&blk) unless RDX.active?
+			RDX.signal_generating do
+				generate_wo_rdx(*args,&blk)
+			end
+		end
+		
+	end
+	
+end
+
+
+
+module RDX
+	
+	class Generator
+
+		# Binds the documentation generator tool +RDoc+ to RDX
+		class RDoc < self
+			
+		# :stopdoc:
+			
+			def custom_options
+				['--force-update']
+			end
+			
+			def document argv=[]
+				@rdoc = ::RDoc::RDoc.new
+				@rdoc.document argv
+			end
+			
+			def directive_rgxp
+				/^
+					\s* :([-\w]+): \ * ( .* )
+				$/ox
+			end
+			
+			def customize_template tmpl
+				# The \z exposed at the end of regexp ensure that optimizations will occurr.
+				# This can be very important with big html files
+				tmpl.sub /<\/footer>\s*\z/, '<p>' + RDX::SIGNATURE + ".\n\\&"
+			end
+			
+			def recognize_examples text
+				vbs = ::RDoc::Markup::Parser.get_verbatims(text)
+				vbs.map{ |vb| [vb.text,vb.line_no] }
+			end
+			
+		end
+
+	end
+
+end