ruby-changes:26600
From: zzak <ko1@a...>
Date: Sat, 29 Dec 2012 16:45:05 +0900 (JST)
Subject: [ruby-changes:26600] zzak:r38651 (trunk): * iseq.c (RubyVM::InstructionSequence): rdoc formatting
zzak 2012-12-29 16:44:54 +0900 (Sat, 29 Dec 2012) New Revision: 38651 http://svn.ruby-lang.org/cgi-bin/viewvc.cgi?view=rev&revision=38651 Log: * iseq.c (RubyVM::InstructionSequence): rdoc formatting Modified files: trunk/ChangeLog trunk/iseq.c Index: ChangeLog =================================================================== --- ChangeLog (revision 38650) +++ ChangeLog (revision 38651) @@ -1,3 +1,7 @@ https://github.com/ruby/ruby/blob/trunk/ChangeLog#L1 +Sat Dec 29 16:45:00 2012 Zachary Scott <zachary@z...> + + * iseq.c (RubyVM::InstructionSequence): rdoc formatting + Sat Dec 29 15:28:00 2012 Zachary Scott <zachary@z...> * iseq.c (RubyVM::InstructionSequence): Add rdoc for new iseq features Index: iseq.c =================================================================== --- iseq.c (revision 38650) +++ iseq.c (revision 38651) @@ -643,8 +643,9 @@ rb_iseq_compile_on_base(VALUE src, VALUE https://github.com/ruby/ruby/blob/trunk/iseq.c#L643 * metadata attached to the returned +iseq+. * * +options+, which can be +true+, +false+ or a +Hash+, is used to - * modify the default behavior of the Ruby iseq compiler. For details - * regarding valid compile options see InstructionSequence.compile_option=. + * modify the default behavior of the Ruby iseq compiler. + * + * For details regarding valid compile options see ::compile_option=. * * RubyVM::InstructionSequence.compile("a = 1 + 2") * #=> <RubyVM::InstructionSequence:<compiled>@<compiled>> @@ -673,8 +674,9 @@ iseq_s_compile(int argc, VALUE *argv, VA https://github.com/ruby/ruby/blob/trunk/iseq.c#L674 * InstructionSequence with source location metadata set. * * Optionally takes +options+, which can be +true+, +false+ or a +Hash+, to - * modify the default behavior of the Ruby iseq compiler (for details see - * InstructionSequence.compile_option=). + * modify the default behavior of the Ruby iseq compiler. + * + * For details regarding valid compile options see ::compile_option=. * * # /tmp/hello.rb * puts "Hello, world!" @@ -713,10 +715,14 @@ iseq_s_compile_file(int argc, VALUE *arg https://github.com/ruby/ruby/blob/trunk/iseq.c#L715 * InstructionSequence.compile_option = options * * Sets the default values for various optimizations in the Ruby iseq - * compiler. Possible values for +options+ include +true+, which enables all - * options, +false+ which disables all options, a +Hash+ of options that you - * want to change (options not present in the hash will be left unchanged), - * and +nil+ which leaves all options unchanged. + * compiler. + * + * Possible values for +options+ include +true+, which enables all options, + * +false+ which disables all options, and +nil+ which leaves all options + * unchanged. + * + * You can also pass a +Hash+ of +options+ that you want to change, any + * options not present in the hash will be left unchanged. * * Possible option names (which are keys in +options+) which can be set to * +true+ or +false+ include: @@ -734,8 +740,7 @@ iseq_s_compile_file(int argc, VALUE *arg https://github.com/ruby/ruby/blob/trunk/iseq.c#L740 * * These default options can be overwritten for a single run of the iseq * compiler by passing any of the above values as the +options+ parameter to - * InstructionSequence.new, InstructionSequence.compile and - * InstructionSequence.compile_file. + * ::new, ::compile and ::compile_file. */ static VALUE iseq_s_compile_option_set(VALUE self, VALUE opt) @@ -752,6 +757,7 @@ iseq_s_compile_option_set(VALUE self, VA https://github.com/ruby/ruby/blob/trunk/iseq.c#L757 * InstructionSequence.compile_option -> options * * Returns a hash of default options used by the Ruby iseq compiler. + * * For details, see InstructionSequence.compile_option=. */ static VALUE @@ -807,11 +813,13 @@ iseq_inspect(VALUE self) https://github.com/ruby/ruby/blob/trunk/iseq.c#L813 /* * Returns the path of this instruction sequence. * + * <code><compiled></code> if the iseq was evaluated from a string. + * * For example, using irb: * - * ins = RubyVM::InstructionSequence.compile('num = 1 + 2') + * iseq = RubyVM::InstructionSequence.compile('num = 1 + 2') * #=> <RubyVM::InstructionSequence:<compiled>@<compiled>> - * ins.path + * iseq.path * #=> "<compiled>" * * Using ::compile_file: @@ -822,8 +830,8 @@ iseq_inspect(VALUE self) https://github.com/ruby/ruby/blob/trunk/iseq.c#L830 * end * * # in irb - * > ins = RubyVM::InstructionSequence.compile_file('/tmp/method.rb') - * > ins.path #=> /tmp/method.rb + * > iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb') + * > iseq.path #=> /tmp/method.rb */ static VALUE iseq_path(VALUE self) @@ -836,6 +844,8 @@ iseq_path(VALUE self) https://github.com/ruby/ruby/blob/trunk/iseq.c#L844 /* * Returns the absolute path of this instruction sequence. * + * +nil+ if the iseq was evaluated from a string. + * * For example, using ::compile_file: * * # /tmp/method.rb @@ -844,8 +854,8 @@ iseq_path(VALUE self) https://github.com/ruby/ruby/blob/trunk/iseq.c#L854 * end * * # in irb - * > ins = RubyVM::InstructionSequence.compile_file('/tmp/method.rb') - * > ins.absolute_path #=> /tmp/method.rb + * > iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb') + * > iseq.absolute_path #=> /tmp/method.rb */ static VALUE iseq_absolute_path(VALUE self) @@ -857,11 +867,14 @@ iseq_absolute_path(VALUE self) https://github.com/ruby/ruby/blob/trunk/iseq.c#L867 /* Returns the label of this instruction sequence. * + * <code><main></code> if it's at the top level, <code><compiled></code> if it + * was evaluated from a string. + * * For example, using irb: * - * ins = RubyVM::InstructionSequence.compile('num = 1 + 2') + * iseq = RubyVM::InstructionSequence.compile('num = 1 + 2') * #=> <RubyVM::InstructionSequence:<compiled>@<compiled>> - * ins.label + * iseq.label * #=> "<compiled>" * * Using ::compile_file: @@ -872,8 +885,8 @@ iseq_absolute_path(VALUE self) https://github.com/ruby/ruby/blob/trunk/iseq.c#L885 * end * * # in irb - * > ins = RubyVM::InstructionSequence.compile_file('/tmp/method.rb') - * > ins.label #=> <main> + * > iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb') + * > iseq.label #=> <main> */ static VALUE iseq_label(VALUE self) @@ -887,9 +900,9 @@ iseq_label(VALUE self) https://github.com/ruby/ruby/blob/trunk/iseq.c#L900 * * For example, using irb: * - * ins = RubyVM::InstructionSequence.compile('num = 1 + 2') + * iseq = RubyVM::InstructionSequence.compile('num = 1 + 2') * #=> <RubyVM::InstructionSequence:<compiled>@<compiled>> - * ins.base_label + * iseq.base_label * #=> "<compiled>" * * Using ::compile_file: @@ -900,8 +913,8 @@ iseq_label(VALUE self) https://github.com/ruby/ruby/blob/trunk/iseq.c#L913 * end * * # in irb - * > ins = RubyVM::InstructionSequence.compile_file('/tmp/method.rb') - * > ins.base_label #=> <main> + * > iseq = RubyVM::InstructionSequence.compile_file('/tmp/method.rb') + * > iseq.base_label #=> <main> */ static VALUE iseq_base_label(VALUE self) @@ -911,13 +924,14 @@ iseq_base_label(VALUE self) https://github.com/ruby/ruby/blob/trunk/iseq.c#L924 return iseq->location.base_label; } -/* Returns the first line number of this instruction sequence. +/* Returns the number of the first source line where the instruction sequence + * was loaded from. * * For example, using irb: * - * ins = RubyVM::InstructionSequence.compile('num = 1 + 2') + * iseq = RubyVM::InstructionSequence.compile('num = 1 + 2') * #=> <RubyVM::InstructionSequence:<compiled>@<compiled>> - * ins.first_lineno + * iseq.first_lineno * #=> 1 */ static VALUE @@ -935,12 +949,12 @@ VALUE iseq_data_to_ary(rb_iseq_t *iseq); https://github.com/ruby/ruby/blob/trunk/iseq.c#L949 * call-seq: * iseq.to_a -> ary * - * Returns an Array of size 14 representing the instruction sequence with - * the following data: + * Returns an Array with 14 elements representing the instruction sequence + * with the following data: * * [magic] - * A string identifying the data format. Always - * "YARVInstructionSequence/SimpleDataFormat". + * A string identifying the data format. <b>Always + * +YARVInstructionSequence/SimpleDataFormat+.</b> * * [major_version] * The major version of the instruction sequence. @@ -949,45 +963,57 @@ VALUE iseq_data_to_ary(rb_iseq_t *iseq); https://github.com/ruby/ruby/blob/trunk/iseq.c#L963 * The minor version of the instruction sequence. * * [format_type] - * A number identifying the data format. Always 1. + * A number identifying the data format. <b>Always 1</b>. * * [misc] - * A hash containing +:arg_size+, the total number of arguments taken by - * the method or the block (0 if _iseq_ doesn't represent a method or - * block), +:local_size+, the number of local variables + 1, and - * +:stack_max+, used in calculating the stack depth at which a - * +SystemStackError+ is thrown. + * A hash containing: + * + * [+:arg_size+] + * the total number of arguments taken by the method or the block (0 if + * _iseq_ doesn't represent a method or block) + * [+:local_size+] + * the number of local variables + 1 + * [+:stack_max+] + * used in calculating the stack depth at which a SystemStackError is + * thrown. * - * [name] + * [#label] * The name of the context (block, method, class, module, etc.) that this - * instruction sequence belongs to. <code><main></code> if it's at the top - * level, <code><compiled></code> if it was evaluated from a string. + * instruction sequence belongs to. * - * [path] + * <code><main></code> if it's at the top level, <code><compiled></code> if + * it was evaluated from a string. + * + * [#path] * The relative path to the Ruby file where the instruction sequence was - * loaded from. <code><compiled></code> if the iseq was evaluated from a - * string. + * loaded from. * - * [absolute_path] + * <code><compiled></code> if the iseq was evaluated from a string. + * + * [#absolute_path] * The absolute path to the Ruby file where the instruction sequence was - * loaded from. +nil+ if the iseq was evaluated from a string. + * loaded from. * - * [start_lineno] + * +nil+ if the iseq was evaluated from a string. + * + * [#first_lineno] * The number of the first source line where the instruction sequence was * loaded from. * * [type] - * The type of the instruction sequence. Valid values are +:top+, - * +:method+, +:block+, +:class+, +:rescue+, +:ensure+, +:eval+, +:main+, - * and +:defined_guard+. + * The type of the instruction sequence. + * + * Valid values are +:top+, +:method+, +:block+, +:class+, +:rescue+, + * +:ensure+, +:eval+, +:main+, and +:defined_guard+. * * [locals] * An array containing the names of all arguments and local variables as * symbols. * * [args] - * The arity if the method or block only has required arguments. Otherwise - * an array of: + * The arity if the method or block only has required arguments. + * + * Otherwise an array of: * * [required_argc, [optional_arg_labels, ...], * splat_index, post_splat_argc, post_splat_index, @@ -2181,17 +2207,20 @@ rb_iseq_line_trace_specify(VALUE iseqval https://github.com/ruby/ruby/blob/trunk/iseq.c#L2207 * Document-class: RubyVM::InstructionSequence * * The InstructionSequence class represents a compiled sequence of - * instructions for the Ruby Virtual Machine. With it, you can get a handle - * to the instructions that make up a method or a proc, compile strings of - * Ruby code down to VM instructions, and disassemble instruction sequences - * to strings for easy inspection. It is mostly useful if you want to learn - * how the Ruby VM works, but it also lets you control various settings for - * the Ruby iseq compiler. You can find the source for the VM instructions in - * +insns.def+ in the Ruby source. - * - * The instruction sequence that results from a given piece of Ruby code will - * almost certainly change as Ruby changes, so example output in this - * documentation may be different from what you see. + * instructions for the Ruby Virtual Machine. + * + * With it, you can get a handle to the instructions that make up a method or + * a proc, compile strings of Ruby code down to VM instructions, and + * disassemble instruction sequences to strings for easy inspection. It is + * mostly useful if you want to learn how the Ruby VM works, but it also lets + * you control various settings for the Ruby iseq compiler. + * + * You can find the source for the VM instructions in +insns.def+ in the Ruby + * source. + * + * The instruction sequence results will almost certainly change as Ruby + * changes, so example output in this documentation may be different from what + * you see. */ void -- ML: ruby-changes@q... Info: http://www.atdot.net/~ko1/quickml/