* 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.


git-svn-id: svn+ssh://ci.ruby-lang.org/ruby/trunk@32281 b2dd03c8-39d4-4d8f-98ff-823fe69b080e

ChangeLog

@@ -1,3 +1,21 @@
+Wed Jun 29 12:07:27 2011  Eric Hodel  <drbrain@segment7.net>
+
+	* 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  <ruby-core@marc-andre.ca>
 
 	* lib/matrix.rb: Matrix.zero can build rectangular matrices.

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);
 }

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);

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
 
 ##

lib/rake.rb

@@ -61,6 +61,8 @@ require 'rake/application'
 
 $trace = false
 
+# :stopdoc:
+#
 # Some top level Constants.
 
 FileList = Rake::FileList

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
+# 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
+# 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

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

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.

math.c

@@ -760,6 +760,8 @@ exp1(sqrt)
  */
 
 /*
+ *  Document-class: Math
+ *
  *  The <code>Math</code> module contains module functions for basic
  *  trigonometric and transcendental functions. See class
  *  <code>Float</code> for a list of constants that

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("==");

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 */

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 <tt>__END__</tt>:
+	 *
+	 *   $ 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);
 }
 

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 <tt>ruby -v</tt> 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));
 }
 

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();