summaryrefslogtreecommitdiff
path: root/lib/rdoc
diff options
context:
space:
mode:
Diffstat (limited to 'lib/rdoc')
-rw-r--r--lib/rdoc/parsers/parse_c.rb226
1 files changed, 133 insertions, 93 deletions
diff --git a/lib/rdoc/parsers/parse_c.rb b/lib/rdoc/parsers/parse_c.rb
index 19b5d443f6..4ebd25c709 100644
--- a/lib/rdoc/parsers/parse_c.rb
+++ b/lib/rdoc/parsers/parse_c.rb
@@ -1,3 +1,78 @@
+# Classes and modules built in to the interpreter. We need
+# these to define superclasses of user objects
+
+require "rdoc/code_objects"
+require "rdoc/parsers/parserfactory"
+require "rdoc/options"
+require "rdoc/rdoc"
+
+module RDoc
+
+ ##
+ # Ruby's built-in classes.
+
+ KNOWN_CLASSES = {
+ "rb_cObject" => "Object",
+ "rb_cArray" => "Array",
+ "rb_cBignum" => "Bignum",
+ "rb_cClass" => "Class",
+ "rb_cDir" => "Dir",
+ "rb_cData" => "Data",
+ "rb_cFalseClass" => "FalseClass",
+ "rb_cFile" => "File",
+ "rb_cFixnum" => "Fixnum",
+ "rb_cFloat" => "Float",
+ "rb_cHash" => "Hash",
+ "rb_cInteger" => "Integer",
+ "rb_cIO" => "IO",
+ "rb_cModule" => "Module",
+ "rb_cNilClass" => "NilClass",
+ "rb_cNumeric" => "Numeric",
+ "rb_cProc" => "Proc",
+ "rb_cRange" => "Range",
+ "rb_cRegexp" => "Regexp",
+ "rb_cString" => "String",
+ "rb_cSymbol" => "Symbol",
+ "rb_cThread" => "Thread",
+ "rb_cTime" => "Time",
+ "rb_cTrueClass" => "TrueClass",
+ "rb_cStruct" => "Struct",
+ "rb_eException" => "Exception",
+ "rb_eStandardError" => "StandardError",
+ "rb_eSystemExit" => "SystemExit",
+ "rb_eInterrupt" => "Interrupt",
+ "rb_eSignal" => "Signal",
+ "rb_eFatal" => "Fatal",
+ "rb_eArgError" => "ArgError",
+ "rb_eEOFError" => "EOFError",
+ "rb_eIndexError" => "IndexError",
+ "rb_eRangeError" => "RangeError",
+ "rb_eIOError" => "IOError",
+ "rb_eRuntimeError" => "RuntimeError",
+ "rb_eSecurityError" => "SecurityError",
+ "rb_eSystemCallError" => "SystemCallError",
+ "rb_eTypeError" => "TypeError",
+ "rb_eZeroDivError" => "ZeroDivError",
+ "rb_eNotImpError" => "NotImpError",
+ "rb_eNoMemError" => "NoMemError",
+ "rb_eFloatDomainError" => "FloatDomainError",
+ "rb_eScriptError" => "ScriptError",
+ "rb_eNameError" => "NameError",
+ "rb_eSyntaxError" => "SyntaxError",
+ "rb_eLoadError" => "LoadError",
+
+ "rb_mKernel" => "Kernel",
+ "rb_mComparable" => "Comparable",
+ "rb_mEnumerable" => "Enumerable",
+ "rb_mPrecision" => "Precision",
+ "rb_mErrno" => "Errno",
+ "rb_mFileTest" => "FileTest",
+ "rb_mGC" => "GC",
+ "rb_mMath" => "Math",
+ "rb_mProcess" => "Process"
+ }
+
+ ##
# We attempt to parse C extension files. Basically we look for
# the standard patterns that you find in extensions: <tt>rb_define_class,
# rb_define_method</tt> and so on. We also try to find the corresponding
@@ -52,8 +127,8 @@
# when the <tt>Init_xxx</tt> method is not named after the class.
#
# [Document-method: <i>name</i>]
- # This comment documents the named method. Use when RDoc cannot outomatically
- # find the method from it's declaration
+ # This comment documents the named method. Use when RDoc cannot
+ # automatically find the method from it's declaration
#
# [call-seq: <i>text up to an empty line</i>]
# Because C source doesn't give descripive names to Ruby-level parameters,
@@ -89,82 +164,9 @@
# */
#
-
- # Classes and modules built in to the interpreter. We need
- # these to define superclasses of user objects
-
-require "rdoc/code_objects"
-require "rdoc/parsers/parserfactory"
-
-
-module RDoc
-
- KNOWN_CLASSES = {
- "rb_cObject" => "Object",
- "rb_cArray" => "Array",
- "rb_cBignum" => "Bignum",
- "rb_cClass" => "Class",
- "rb_cDir" => "Dir",
- "rb_cData" => "Data",
- "rb_cFalseClass" => "FalseClass",
- "rb_cFile" => "File",
- "rb_cFixnum" => "Fixnum",
- "rb_cFloat" => "Float",
- "rb_cHash" => "Hash",
- "rb_cInteger" => "Integer",
- "rb_cIO" => "IO",
- "rb_cModule" => "Module",
- "rb_cNilClass" => "NilClass",
- "rb_cNumeric" => "Numeric",
- "rb_cProc" => "Proc",
- "rb_cRange" => "Range",
- "rb_cRegexp" => "Regexp",
- "rb_cString" => "String",
- "rb_cSymbol" => "Symbol",
- "rb_cThread" => "Thread",
- "rb_cTime" => "Time",
- "rb_cTrueClass" => "TrueClass",
- "rb_cStruct" => "Struct",
- "rb_eException" => "Exception",
- "rb_eStandardError" => "StandardError",
- "rb_eSystemExit" => "SystemExit",
- "rb_eInterrupt" => "Interrupt",
- "rb_eSignal" => "Signal",
- "rb_eFatal" => "Fatal",
- "rb_eArgError" => "ArgError",
- "rb_eEOFError" => "EOFError",
- "rb_eIndexError" => "IndexError",
- "rb_eRangeError" => "RangeError",
- "rb_eIOError" => "IOError",
- "rb_eRuntimeError" => "RuntimeError",
- "rb_eSecurityError" => "SecurityError",
- "rb_eSystemCallError" => "SystemCallError",
- "rb_eTypeError" => "TypeError",
- "rb_eZeroDivError" => "ZeroDivError",
- "rb_eNotImpError" => "NotImpError",
- "rb_eNoMemError" => "NoMemError",
- "rb_eFloatDomainError" => "FloatDomainError",
- "rb_eScriptError" => "ScriptError",
- "rb_eNameError" => "NameError",
- "rb_eSyntaxError" => "SyntaxError",
- "rb_eLoadError" => "LoadError",
-
- "rb_mKernel" => "Kernel",
- "rb_mComparable" => "Comparable",
- "rb_mEnumerable" => "Enumerable",
- "rb_mPrecision" => "Precision",
- "rb_mErrno" => "Errno",
- "rb_mFileTest" => "FileTest",
- "rb_mGC" => "GC",
- "rb_mMath" => "Math",
- "rb_mProcess" => "Process"
-
- }
-
- # See rdoc/c_parse.rb
-
class C_Parser
+ attr_accessor :progress
extend ParserFactory
parse_files_matching(/\.(c|cc|cpp|CC)$/)
@@ -217,8 +219,9 @@ module RDoc
comment.sub!(/\/?\*--.*/m, '')
end
- # remove lines that are commented out that might otherwise get
- # picked up when scanning for classes and methods
+ ##
+ # removes lines that are commented out that might otherwise get picked up
+ # when scanning for classes and methods
def remove_commented_out_lines
@body.gsub!(%r{//.*rb_define_}, '//')
@@ -260,7 +263,6 @@ module RDoc
@classes[var_name] = cm
@known_classes[var_name] = cm.full_name
end
-
############################################################
@@ -425,7 +427,16 @@ module RDoc
end
end
- ############################################################
+ ##
+ # Adds constant comments. By providing some_value: at the start ofthe
+ # comment you can override the C value of the comment to give a friendly
+ # definition.
+ #
+ # /* 300: The perfect score in bowling */
+ # rb_define_const(cFoo, "PERFECT", INT2FIX(300);
+ #
+ # Will override +INT2FIX(300)+ with the value +300+ in the output RDoc.
+ # Values may include quotes and escaped colons (\:).
def handle_constants(type, var_name, const_name, definition)
#@stats.num_constants += 1
@@ -442,14 +453,39 @@ module RDoc
comment = find_const_comment(type, const_name)
- con = Constant.new(const_name, definition, mangle_comment(comment))
+ # In the case of rb_define_const, the definition and comment are in
+ # "/* definition: comment */" form. The literal ':' and '\' characters
+ # can be escaped with a backslash.
+ if type.downcase == 'const' then
+ elements = mangle_comment(comment).split(':')
+ if elements.nil? or elements.empty? then
+ con = Constant.new(const_name, definition, mangle_comment(comment))
+ else
+ new_definition = elements[0..-2].join(':')
+ if new_definition.empty? then # Default to literal C definition
+ new_definition = definition
+ else
+ new_definition.gsub!("\:", ":")
+ new_definition.gsub!("\\", '\\')
+ end
+ new_definition.sub!(/\A(\s+)/, '')
+ new_comment = $1.nil? ? elements.last : "#{$1}#{elements.last.lstrip}"
+ con = Constant.new(const_name, new_definition,
+ mangle_comment(new_comment))
+ end
+ else
+ con = Constant.new(const_name, definition, mangle_comment(comment))
+ end
+
class_obj.add_constant(con)
end
- ###########################################################
+ ##
+ # Finds a comment matching +type+ and +const_name+ either above the
+ # comment or in the matching Document- section.
def find_const_comment(type, const_name)
- if @body =~ %r{((?>/\*.*?\*/\s+))
+ if @body =~ %r{((?>^\s*/\*.*?\*/\s+))
rb_define_#{type}\((?:\s*(\w+),)?\s*"#{const_name}"\s*,.*?\)\s*;}xmi
$1
elsif @body =~ %r{Document-(?:const|global|variable):\s#{const_name}\s*?\n((?>.*?\*/))}m
@@ -610,13 +646,15 @@ module RDoc
end
- ##################################################
- #
- # If the comment block contains a section that looks like
+ ##
+ # If the comment block contains a section that looks like:
+ #
# call-seq:
# Array.new
# Array.new(10)
- # use it for the parameters
+ #
+ # use it for the parameters.
+
def find_modifiers(comment, meth_obj)
if comment.sub!(/:nodoc:\s*^\s*\*?\s*$/m, '') or
comment.sub!(/\A\/\*\s*:nodoc:\s*\*\/\Z/, '')
@@ -639,10 +677,11 @@ module RDoc
end
end
- ############################################################
-
- # Look for includes of the form
+ ##
+ # Look for includes of the form:
+ #
# rb_include_module(rb_cArray, rb_mEnumerable);
+
def do_includes
@body.scan(/rb_include_module\s*\(\s*(\w+?),\s*(\w+?)\s*\)/) do |c,m|
if cls = @classes[c]
@@ -652,8 +691,7 @@ module RDoc
end
end
- ############################################################
-
+ ##
# Remove the /*'s and leading asterisks from C comments
def mangle_comment(comment)
@@ -686,7 +724,8 @@ module RDoc
end
end
- # Remove #ifdefs that would otherwise confuse us
+ ##
+ # Removes #ifdefs that would otherwise confuse us
def handle_ifdefs_in(body)
body.gsub(/^#ifdef HAVE_PROTOTYPES.*?#else.*?\n(.*?)#endif.*?\n/m) { $1 }
@@ -695,3 +734,4 @@ module RDoc
end
end
+