I think there are lots of holes in the ruby lib docs, and I would like to fill
them. I, too, have the impression that docs posted to this list are sometimes
blackholed.
How about a roll-call:
who on this list has commit access?
who on this list is comfortable (or has authority) to commit doc
changes to the lib for modules they do not maintain?
how do you find the maintainer of a library, so you can send docs to them
if this isn't the right place?
I'd love to see some kind of queue, like doc patches are posted here with
[patch], and when committed they are replied to with [patch-commit], and
somebody willing to commit docs anywhere. Maybe thats too much for now, though?
Maybe if specific maintainers want to have control over exactly how their
library is documented, they can commit to responding quickly to doc patches and
put a comment to that effect at the top of their libs.
And maybe others are happy to have somebody else document their library, and
somebody on this list can just patch the docs in without asking them.
I often find that I need to look in ruby lib to see how something works.
When I figure it out, it only takes a few minutes to type into the src
the description, and send a cvs diff here. It can take longet to get them
committed than to write them!
I really, really like ruby, and I really want other people (and me!) to be
able to look at the docs and understand how to use the library.
Cheers,
Sam
Example:
Partial docs for Resolv::DNS::Name, I have a pretty good understanding
of this lib right now, I'd add a lot more docs if I KNEW the maintainer
would happily merge them into the source.
@@ -951,7 +965,10 @@
end
end
+ # A DNS name, a sequence of labels seperated by a +.+.
class Name
+ # Create a Name from a Name (in which case +arg+ is returned
+ # directly), or from a String (in which case a new Name is returned).
def self.create(arg)
case arg
when Name
@@ -963,15 +980,22 @@
end
end
- def initialize(labels, absolute=true)
+ def initialize(labels, absolute=true) # :nodoc:
@labels = labels
@absolute = absolute
end
+ # The name had a terminating +.+, for example:
+ # example.com.
+ # is absolute, whereas:
+ # example.com
+ # is not. Absolute names will never have the default search domains
+ # added to them during resolution.
def absolute?
return @absolute
end
+ # True if the name's labels are equal, where the match is
case-insensitive.
+ # Also, the "absolute?" attribute must also match, so "example.com"
+ # and "example.com." are not equal!
def ==(other)
return @labels == other.to_a && @absolute == other.absolute?
end
Quoteing jbritt@xxxxxxxxxxxx, on Mon, Jan 24, 2005 at 06:19:25AM -0700:
> Zev Blut wrote:
> >Hello,
> >
> >I sent a mail over a month ago with a suggestion to add a few extra
> >details to the Open3.popen3 method. Hopefully, everyone was busy and
> >that is why there was no reply. Here is the mail again. If this is
> >not the proper place for documentation additions where is?
>
> I'd like to think this is the first place you should go, but if you do
> not get a clear answer than I'd suggest the ruby-core mailing list,
> where there may be a greater chance of getting the attention of whomever
> maintains the code.
>
> BTW, a question for all those on the list: I've heard this problem
> before, where someone is not sure where to post doc patches. What is
> the best path for people who have some doc correction/addition, and
> simply want to get the changes into the code without jumping through hoops?
>
> I've been telling people to just post here, and that someone will pick
> up on it, but maybe that's just not true.
>
> Suggestions?
>
>
> James
>
|
