diff --git a/ChangeLog b/ChangeLog index 8b14f5a5cf..5cc4987e98 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,21 @@ +Wed Jun 29 12:07:27 2011 Eric Hodel + + * math.c: Attach documentation for Math. + * object.c: Document NIL, TRUE, FALSE. + * io.c: Improve grammar in ARGF comment. Document STDIN/OUT/ERR. + Document ARGF global constant. + * lib/rake: Hide deprecated toplevel constants from RDoc (import from + rake trunk). + * lib/thwait.rb: Document ThWait. + * lib/mathn.rb: Hide Math redefinition from RDoc + * lib/sync.rb: Add a basic comment for Sync_m, Synchronizer_m, Sync, + Synchronizer. + * parse.y: Document SCRIPT_LINES__. + * hash.c: Document ENV class and global constant. + * vm.c: Document TOPLEVEL_BINDING. + * version.c: Document RUBY_* constants. + * ruby.c: Document DATA and ARGV. + Wed Jun 29 10:13:12 2011 Marc-Andre Lafortune * lib/matrix.rb: Matrix.zero can build rectangular matrices. diff --git a/hash.c b/hash.c index 4b5cd33b0d..b49aff8a61 100644 --- a/hash.c +++ b/hash.c @@ -2974,6 +2974,15 @@ Init_Hash(void) rb_define_method(rb_cHash,"compare_by_identity", rb_hash_compare_by_id, 0); rb_define_method(rb_cHash,"compare_by_identity?", rb_hash_compare_by_id_p, 0); + /* Document-class: ENV + * + * ENV is a hash-like accessor for environment variables. + */ + + /* + * Hack to get RDoc to regard ENV as a class: + * envtbl = rb_define_class("ENV", rb_cObject); + */ origenviron = environ; envtbl = rb_obj_alloc(rb_cObject); rb_extend_object(envtbl, rb_mEnumerable); @@ -3020,5 +3029,10 @@ Init_Hash(void) rb_define_singleton_method(envtbl,"assoc", env_assoc, 1); rb_define_singleton_method(envtbl,"rassoc", env_rassoc, 1); + /* + * ENV is a Hash-like accessor for environment variables. + * + * See ENV (the class) for more details. + */ rb_define_global_const("ENV", envtbl); } diff --git a/io.c b/io.c index 4371d5388a..7900ab6638 100644 --- a/io.c +++ b/io.c @@ -10320,7 +10320,7 @@ argf_write(VALUE argf, VALUE str) * Document-class: ARGF * * +ARGF+ is a stream designed for use in scripts that process files given as - * command-line arguments, or passed in via STDIN. + * command-line arguments or passed in via STDIN. * * The arguments passed to your script are stored in the +ARGV+ Array, one * argument per element. +ARGF+ assumes that any arguments that aren't @@ -10336,7 +10336,7 @@ argf_write(VALUE argf, VALUE str) * files. For instance, +ARGF.read+ will return the contents of _file1_ * followed by the contents of _file2_. * - * After a file in +ARGV+ has been read, +ARGF+ removes it from the Array. + * After a file in +ARGV+ has been read +ARGF+ removes it from the Array. * Thus, after all files have been read +ARGV+ will be empty. * * You can manipulate +ARGV+ yourself to control what +ARGF+ operates on. If @@ -10628,9 +10628,11 @@ Init_IO(void) orig_stdout = rb_stdout; rb_deferr = orig_stderr = rb_stderr; - /* constants to hold original stdin/stdout/stderr */ + /* Holds the original stdin */ rb_define_global_const("STDIN", rb_stdin); + /* Holds the original stdout */ rb_define_global_const("STDOUT", rb_stdout); + /* Holds the original stderr */ rb_define_global_const("STDERR", rb_stderr); /* @@ -10707,6 +10709,12 @@ Init_IO(void) argf = rb_class_new_instance(0, 0, rb_cARGF); rb_define_readonly_variable("$<", &argf); + /* + * ARGF is a stream designed for use in scripts that process files given + * as command-line arguments or passed in via STDIN. + * + * See ARGF (the class) for more details. + */ rb_define_global_const("ARGF", argf); rb_define_hooked_variable("$.", &argf, argf_lineno_getter, argf_lineno_setter); diff --git a/lib/mathn.rb b/lib/mathn.rb index fa4576f1c1..b1a959d8f8 100644 --- a/lib/mathn.rb +++ b/lib/mathn.rb @@ -49,7 +49,7 @@ require "mathn/complex" unless defined?(Math.exp!) Object.instance_eval{remove_const :Math} - Math = CMath + Math = CMath # :nodoc: end ## diff --git a/lib/rake.rb b/lib/rake.rb index 31fa1fa579..fc1a6a5165 100644 --- a/lib/rake.rb +++ b/lib/rake.rb @@ -61,6 +61,8 @@ require 'rake/application' $trace = false +# :stopdoc: +# # Some top level Constants. FileList = Rake::FileList diff --git a/lib/rake/contrib/publisher.rb b/lib/rake/contrib/publisher.rb index baa9a3607d..8b11edb59c 100644 --- a/lib/rake/contrib/publisher.rb +++ b/lib/rake/contrib/publisher.rb @@ -1,15 +1,19 @@ # Copyright 2003-2010 by Jim Weirich (jim.weirich@gmail.com) # All rights reserved. +# :stopdoc: + # Configuration information about an upload host system. -# * name :: Name of host system. -# * webdir :: Base directory for the web information for the -# application. The application name (APP) is appended to -# this directory before using. -# * pkgdir :: Directory on the host system where packages can be -# placed. +# name :: Name of host system. +# webdir :: Base directory for the web information for the +# application. The application name (APP) is appended to +# this directory before using. +# pkgdir :: Directory on the host system where packages can be +# placed. HostInfo = Struct.new(:name, :webdir, :pkgdir) +# :startdoc: + # Manage several publishers as a single entity. class CompositePublisher def initialize diff --git a/lib/sync.rb b/lib/sync.rb index bb2ad2b00f..bae05a4a99 100644 --- a/lib/sync.rb +++ b/lib/sync.rb @@ -41,6 +41,9 @@ unless defined? Thread raise "Thread not available for this ruby interpreter" end +## +# A module that provides a two-phase lock with a counter. + module Sync_m RCS_ID='-$Id$-' @@ -298,9 +301,21 @@ module Sync_m return ret end end + +## +# An alias for Sync_m from sync.rb + Synchronizer_m = Sync_m +## +# A class that providesa two-phase lock with a counter. See Sync_m for +# details. + class Sync include Sync_m end + +## +# An alias for Sync from sync.rb. See Sync_m for details. + Synchronizer = Sync diff --git a/lib/thwait.rb b/lib/thwait.rb index b5574a1c28..f5876236e4 100644 --- a/lib/thwait.rb +++ b/lib/thwait.rb @@ -131,13 +131,12 @@ class ThreadsWait end end -ThWait = ThreadsWait +## +# An alias for ThreadsWait from thwait.rb +ThWait = ThreadsWait # Documentation comments: # - Source of documentation is evenly split between Nutshell, existing # comments, and my own rephrasing. # - I'm not particularly confident that the comments are all exactly correct. -# - The history, etc., up the top appears in the RDoc output. Perhaps it would -# be better to direct that not to appear, and put something else there -# instead. diff --git a/math.c b/math.c index 7e073d7fe7..b3ac188d94 100644 --- a/math.c +++ b/math.c @@ -760,6 +760,8 @@ exp1(sqrt) */ /* + * Document-class: Math + * * The Math module contains module functions for basic * trigonometric and transcendental functions. See class * Float for a list of constants that diff --git a/object.c b/object.c index 93ff4780e6..57b349a9c3 100644 --- a/object.c +++ b/object.c @@ -2677,6 +2677,9 @@ Init_Object(void) rb_define_method(rb_cNilClass, "nil?", rb_true, 0); rb_undef_alloc_func(rb_cNilClass); rb_undef_method(CLASS_OF(rb_cNilClass), "new"); + /* + * An alias of +nil+ + */ rb_define_global_const("NIL", Qnil); rb_define_method(rb_cModule, "freeze", rb_mod_freeze, 0); @@ -2746,6 +2749,9 @@ Init_Object(void) rb_define_method(rb_cTrueClass, "^", true_xor, 1); rb_undef_alloc_func(rb_cTrueClass); rb_undef_method(CLASS_OF(rb_cTrueClass), "new"); + /* + * An alias of +true+ + */ rb_define_global_const("TRUE", Qtrue); rb_cFalseClass = rb_define_class("FalseClass", rb_cObject); @@ -2755,6 +2761,9 @@ Init_Object(void) rb_define_method(rb_cFalseClass, "^", false_xor, 1); rb_undef_alloc_func(rb_cFalseClass); rb_undef_method(CLASS_OF(rb_cFalseClass), "new"); + /* + * An alias of +false+ + */ rb_define_global_const("FALSE", Qfalse); id_eq = rb_intern("=="); diff --git a/parse.y b/parse.y index db33723531..12b49fd6bc 100644 --- a/parse.y +++ b/parse.y @@ -10750,5 +10750,17 @@ Init_ripper(void) /* ensure existing in symbol table */ (void)rb_intern("||"); (void)rb_intern("&&"); + +# if 0 + /* Hack to let RDoc document SCRIPT_LINES__ */ + + /* + * When a Hash is assigned to +SCRIPT_LINES__+ the contents of files loaded + * after the assignment will be added as an Array of lines with the file + * name as the key. + */ + rb_define_global_const("SCRIPT_LINES__", Qnil); +#endif + } #endif /* RIPPER */ diff --git a/ruby.c b/ruby.c index f831b651c7..cb27d163a5 100644 --- a/ruby.c +++ b/ruby.c @@ -1625,6 +1625,18 @@ load_file_internal(VALUE arg) tree = rb_parser_compile_file(parser, fname, f, line_start); rb_funcall(f, set_encoding, 1, rb_parser_encoding(parser)); if (script && tree && rb_parser_end_seen_p(parser)) { + /* + * DATA is a File that contains the data section of the executed file. + * To create a data section use __END__: + * + * $ cat t.rb + * puts DATA.gets + * __END__ + * hello world! + * + * $ ruby t.rb + * hello world! + */ rb_define_global_const("DATA", f); } else if (f != rb_stdin) { @@ -1746,6 +1758,13 @@ ruby_prog_init(void) rb_define_hooked_variable("$0", &rb_progname, 0, set_arg0); rb_define_hooked_variable("$PROGRAM_NAME", &rb_progname, 0, set_arg0); + /* + * ARGV contains the command line arguments used to run ruby with the + * first value containing the name of the executable. + * + * A library like OptionParser can be used to process command-line + * arguments. + */ rb_define_global_const("ARGV", rb_argv); } diff --git a/version.c b/version.c index 9cf37af111..59d4e5e411 100644 --- a/version.c +++ b/version.c @@ -98,13 +98,38 @@ const char ruby_initial_load_paths[] = void Init_version(void) { + /* + * The running version of ruby + */ rb_define_global_const("RUBY_VERSION", MKSTR(version)); + /* + * The date this ruby was released + */ rb_define_global_const("RUBY_RELEASE_DATE", MKSTR(release_date)); + /* + * The platform for this ruby + */ rb_define_global_const("RUBY_PLATFORM", MKSTR(platform)); + /* + * The patchlevel for this ruby. If this is a development build of ruby + * the patchlevel will be -1 + */ rb_define_global_const("RUBY_PATCHLEVEL", INT2FIX(RUBY_PATCHLEVEL)); + /* + * The SVN revision for this ruby. + */ rb_define_global_const("RUBY_REVISION", INT2FIX(RUBY_REVISION)); + /* + * The full ruby version string, like ruby -v prints' + */ rb_define_global_const("RUBY_DESCRIPTION", MKSTR(description)); + /* + * The copyright string for ruby + */ rb_define_global_const("RUBY_COPYRIGHT", MKSTR(copyright)); + /* + * The engine or interpreter this ruby uses. + */ rb_define_global_const("RUBY_ENGINE", ruby_engine_name = MKSTR(engine)); } diff --git a/vm.c b/vm.c index e69d0db56a..d945fba0d7 100644 --- a/vm.c +++ b/vm.c @@ -2128,6 +2128,9 @@ Init_VM(void) th->cfp->pc = iseq->iseq_encoded; th->cfp->self = th->top_self; + /* + * The Binding of the top level scope + */ rb_define_global_const("TOPLEVEL_BINDING", rb_binding_new()); } vm_init_redefined_flag();