James, Gavin -
Judging from your emails, I hear two issues:
GS - that the auto-generated docs might not get generated right, so we'd
be automatically putting junk on ruby-doc.org
JB - that if we put a new .zip file up every day, people might download
it every day.. and maybe the docs don't change that fast!
I don't generate the entire docset regularly on my machine, I did it
once, and regenerate specific libs after I've added docs to make sure
they generate OK. So, there could be problems, but its not possible for
one guy to check, and no amount of me running it on my machine is going
to have me say "yep, the docs are good". I've never even looked at some
of the packages, they could be chop suey inside.
Here's a suggestion that might help both issues.
How about the stdlib docs have a "stable" version, and a "nightly"
version. We can ask that people look at the nightly version, and if
there are problems, to report them. That way we get all eyes checking,
and will discover problems faster.
If it is totally hosed by an auto-build, they can then look at the
"stable" version (and report it), they won't be totally out of luck.
If there is no .zip file for the nightly, folks are more likely to
check the online and report problems, and there won't be giant zip file
downloads every day, either.
Every 'once in a while' after nobody has reported problems with the
nightly, it can be moved over to stable, and the announcement can go
out.
There's all kinds of cool tools, and scripts that could be done to get a
metric for how many comment lines have changed, and how much the docs
have changed, and I wouldn't discourage anybody from doing it. But..
I'd rather see the time going into rdocifying some rd-documented lib in
cvs.
Maybe I'm too optimistic, but I really hope that if docs patches could
be posted, show up in cvs, and be on the web page faster than we'd get
more docs posted by volunteers. Also if there was a one-two-three step
to submitting some docs:
1 - co src like this...
2 - add docs...
3 - install stdlib-doc and run ....
4 - mail diff -u to ruby-doc@ with subject of ...
Even thats a fair bit of work!
Anyhow, maybe I have a uniquely bad memory thus forcing me to write down
things I learn about the libs before I forget, and nobody else shares my
problem. I don't have time to take a whole lib and document, but I can
do one function at a time, I wish it was a little easier and faster.
Sam
Btw, here's my local tree's diffs.
Index: process.c
===================================================================
RCS file: /src/ruby/process.c,v
retrieving revision 1.92.2.18
diff -u -r1.92.2.18 process.c
--- process.c 28 Feb 2005 02:45:19 -0000 1.92.2.18
+++ process.c 9 Mar 2005 20:38:28 -0000
@@ -1546,7 +1546,7 @@
* number of seconds slept (rounded), which may be less than that asked
* for if the thread was interrupted by a +SIGALRM+, or if
* another thread calls <code>Thread#run</code>. Zero arguments
- * causes +sleep+ to sleep forever.
+ * causes +sleep+ to sleep forever (until it is woken).
*
* Time.new #=> Wed Apr 09 08:56:32 CDT 2003
* sleep 1.2 #=> 1
Index: re.c
===================================================================
RCS file: /src/ruby/re.c,v
retrieving revision 1.114.2.12
diff -u -r1.114.2.12 re.c
--- re.c 6 Feb 2005 03:23:40 -0000 1.114.2.12
+++ re.c 9 Mar 2005 20:38:28 -0000
@@ -1627,7 +1627,7 @@
* options are propagated, and new options may not be specified (a change as
of
* Ruby 1.8). If <i>options</i> is a <code>Fixnum</code>, it should be one or
* more of the constants <code>Regexp::EXTENDED</code>,
- * <code>Regexp::IGNORECASE</code>, and <code>Regexp::POSIXLINE</code>,
+ * <code>Regexp::IGNORECASE</code>, and <code>Regexp::MULTILINE</code>,
* <em>or</em>-ed together. Otherwise, if <i>options</i> is not
* <code>nil</code>, the regexp will be case insensitive. The <i>lang</i>
* parameter enables multibyte support for the regexp: `n', `N' = none, `e',
Index: ext/iconv/iconv.c
===================================================================
RCS file: /src/ruby/ext/iconv/iconv.c,v
retrieving revision 1.16.2.5
diff -u -r1.16.2.5 iconv.c
--- ext/iconv/iconv.c 4 Mar 2005 10:39:45 -0000 1.16.2.5
+++ ext/iconv/iconv.c 9 Mar 2005 20:38:28 -0000
@@ -628,7 +628,7 @@
}
/*
- * Document-method: Iconv::conv
+ * Document-method: Iconv::iconv
* call-seq: Iconv.iconv(to, from, *strs)
*
* Shorthand for
Index: lib/pp.rb
===================================================================
RCS file: /src/ruby/lib/pp.rb,v
retrieving revision 1.27.2.13
diff -u -r1.27.2.13 pp.rb
--- lib/pp.rb 6 Mar 2005 02:57:53 -0000 1.27.2.13
+++ lib/pp.rb 9 Mar 2005 20:38:29 -0000
@@ -274,6 +274,17 @@
#
# However, doing this requires that every class that #inspect is called on
# implement #pretty_print, or a RuntimeError will be raised.
+ #
+ # If you just want a simple way to get the string representation for an
Object
+ # in the same format #pp prints it, it is possible to do something like:
+ # module Kernel
+ # def pp_str
+ # s = PP.pp(self, '')
+ # s.chomp!
+ # s
+ # end
+ # end
+ # This can be useful when it is put in your ~/.irbrc file, for example.
def pretty_print_inspect
if /\(PP::ObjectMixin\)#/ =~ method(:pretty_print).inspect
raise "pretty_print is not overridden."
Index: lib/thread.rb
===================================================================
RCS file: /src/ruby/lib/thread.rb,v
retrieving revision 1.16.2.1
diff -u -r1.16.2.1 thread.rb
--- lib/thread.rb 27 May 2004 07:50:04 -0000 1.16.2.1
+++ lib/thread.rb 9 Mar 2005 20:38:30 -0000
@@ -232,9 +232,50 @@
#
# This class provides a way to communicate data between threads.
#
-# TODO: an example (code or English) would really help here. How do you set up
-# a queue between two threads?
+# It implements the classic "producer-consumer" mechanism. One (or more)
+# threads push objects on the Queue, one (or more) threads pop objects from the
+# queue.
#
+# require 'timeout'
+# require 'thread'
+# require 'pp'
+#
+# class TimeService
+# def initialize(&proc)
+# @thread = Thread.new do
+# begin
+# loop do
+# sleep 1
+# proc.call(Time.now)
+# end
+# ensure
+# # cleanup?
+# end
+# end
+# end
+#
+# def stop
+# @thread.kill
+# end
+# end
+#
+# queue = Queue.new
+#
+# svc = TimeService.new do |t|
+# queue.push(t)
+# end
+#
+# begin
+# timeout(5) do
+# loop do
+# pp queue.pop
+# end
+# end
+# rescue Timeout::Error
+# ensure
+# svc.stop
+# end
+
class Queue
#
# Creates a new queue.
@@ -307,13 +348,7 @@
def length
@que.length
end
-
- #
- # Alias of length.
- #
- def size
- length
- end
+ alias size length
#
# Returns the number of threads waiting on the queue.
@@ -370,6 +405,9 @@
max
end
+ # Like Queue#push, but will block if the current Queue#length is equal
+ # to #max. Pushers will be woken up (in the order in which they were blocked)
+ # when an object is popped from the SizedQueue.
def push(obj)
Thread.critical = true
while @que.length >= @max
@@ -382,6 +420,8 @@
alias << push
alias enq push
+ # Like Queue#pop, but if there are any Threads blocked in a #push, they
+ # will be allowed to continue.
def pop(*args)
retval = super
Thread.critical = true
@@ -404,6 +444,9 @@
alias shift pop
alias deq pop
+ # The number or waiting "poppers" and of waiting "pushers".
+ # FIXME - it seems less than useful, this... why leave num_waiting as Queue
+ # defines it, and introduce a new attribute for pushers?
def num_waiting
@waiting.size + @queue_wait.size
end
Index: lib/rdoc/template.rb
===================================================================
RCS file: /src/ruby/lib/rdoc/template.rb,v
retrieving revision 1.1
diff -u -r1.1 template.rb
--- lib/rdoc/template.rb 1 Dec 2003 07:12:48 -0000 1.1
+++ lib/rdoc/template.rb 9 Mar 2005 20:38:30 -0000
@@ -25,13 +25,13 @@
#
# Usage: Given a set of templates <tt>T1, T2,</tt> etc
#
-# values = { "name" => "Dave", state => "TX" }
+# values = { "name" => "Dave", "state" => "TX" }
#
# t = TemplatePage.new(T1, T2, T3)
# File.open(name, "w") {|f| t.write_html_on(f, values)}
# or
# res = ''
-# t.write_html_on(res, values)
+# puts t.write_html_on(res, values)
#
#
@@ -138,7 +138,9 @@
end
# Render the templates into HTML, storing the result on +op+
- # using the method <tt><<</tt>. The <tt>value_hash</tt> contains
+ # using the method <tt><<</tt>. Returns +op+. If you want
+ # the template as a String, pass '' as +op+, and the template
+ # will be appended to the end and returned. The +value_hash+ contains
# key/value pairs used to drive the substitution (as described above)
def write_html_on(op, value_hash)
@@ -195,7 +197,7 @@
result.join("\n")
end
- # Given an individual line, we look for %xxx% constructs and
+ # Given an individual +line+, we look for %xxx% constructs and
# HREF:ref:name: constructs, substituting for each.
def expand_line(line)
|
