Are there any plans to add docs for modules like Socket and OpenSSL, etc to
either the 1.6 reference, ri or the stdlib docs at ruby-doc.org ?
If someone can tell me what should be done I could probably get started
on the docs myself.
Of course, if they’re already out there (in more than the 1.4.6 ref), I’d love
a pointer :->
···
Jim Hranicky, Senior SysAdmin UF/CISE Department |
E314D CSE Building Phone (352) 392-1499 |
jfh@cise.ufl.edu http://www.cise.ufl.edu/~jfh |
About politics:
Don't worry about results
It's the thought that counts
www.ruby-doc.org may help. It has many documentation available.
There is also an effort to document the whole standard library going
on, yo may get info at that site .
···
il Wed, 10 Dec 2003 23:20:21 +0900, “James F. Hranicky” jfh@cise.ufl.edu ha scritto::
Are there any plans to add docs for modules like Socket and OpenSSL, etc to
either the 1.6 reference, ri or the stdlib docs at ruby-doc.org ?
If someone can tell me what should be done I could probably get started
on the docs myself.
Of course, if they’re already out there (in more than the 1.4.6 ref), I’d love
a pointer :->
Are there any plans to add docs for modules like Socket and OpenSSL, etc to
either the 1.6 reference, ri or the stdlib docs at ruby-doc.org ?
I have plans to put them in the latter, but those are very long-term
plans, for the reason mentioned below.
If someone can tell me what should be done I could probably get started
on the docs myself.
That would be great. Since the modules you mention are implemented in
C, they fall outside my current project of getting the Ruby-language
standard libraries documented at you-know-where.
If you want to add some RDoc comments to the C files, I’ll make an
effort to include it in the published documentation. You can email me
or the ruby-doc ML with any questions.
Of course, if they’re already out there (in more than the 1.4.6 ref), I’d love
a pointer :->>
From memory, the PickAxe describes Socket reasonably well. I don’t
remember OpenSSL, though.
Cheers,
Gavin
···
On Thursday, December 11, 2003, 1:20:21 AM, James wrote:
Don’t know…
I found a README file for OpenSSL which may be useful?
http://www.nongnu.org/rubypki/README
···
On Wed, 10 Dec 2003 23:20:21 +0900, James F. Hranicky wrote:
Are there any plans to add docs for modules like Socket and OpenSSL, etc to
either the 1.6 reference, ri or the stdlib docs at ruby-doc.org ?
–
Simon Strandgaard
I found that too, but I’d rather not have to dig around for docs, especially
if the module in question has been integrated into Ruby itself. I’d like to
see everything under ext with docs in the standard reference, so that all the
base Ruby documentation is in one place.
Since I’m griping, I’m also volunteering, so if anyone has pointers I’d like
to hear them, otherwise, I’ll add RDoc comments to the C files as per Gavin’s
suggestion.
Jim
···
On Thu, 11 Dec 2003 20:57:00 +0900 Simon Strandgaard neoneye@adslhome.dk wrote:
On Wed, 10 Dec 2003 23:20:21 +0900, James F. Hranicky wrote:
Are there any plans to add docs for modules like Socket and OpenSSL, etc to
either the 1.6 reference, ri or the stdlib docs at ruby-doc.org ?
Don’t know…
I found a README file for OpenSSL which may be useful?
http://www.nongnu.org/rubypki/README
Ok, I’ve added a tiny blurb for UNIXServer::accept, and I see it show up in
the newly formed docs. I want to add something like this for UNIXServer.open:
/*
- Open a UNIX domain socket, e.g.:
···
On Thu, 11 Dec 2003 18:06:01 +0900 Gavin Sinclair gsinclair@soyabean.com.au wrote:
If you want to add some RDoc comments to the C files, I’ll make an
effort to include it in the published documentation. You can email me
or the ruby-doc ML with any questions.
- s = UNIXServer.open(“/tmp/sock”)
- UNIXServer.open(“/tmp/sock”) { |s| n = s.accept; n.puts(“you connected!”) }
*/
but as there is no corresponding rb_define_method() entry for UNIXServer.open,
it doesn’t show up.
Any pointers on where this should go?
Jim
smack duhhh…
This, and the doc for UNIXServer.new, should go in the initialize doc, right?
Jim
···
On Thu, 11 Dec 2003 22:13:10 +0900 “James F. Hranicky” jfh@cise.ufl.edu wrote:
/*
- Open a UNIX domain socket, e.g.:
- s = UNIXServer.open(“/tmp/sock”)
- UNIXServer.open(“/tmp/sock”) { |s| n = s.accept; n.puts(“you connected!”) }
*/
but as there is no corresponding rb_define_method() entry for UNIXServer.open,
it doesn’t show up.
Any pointers on where this should go?
Hold off for just a week or two: RDoc might change just slightly as I
add ri integration. I’ve got the basics working, but I want to play a
bit before releasing.
Cheers
Dave
···
On Dec 11, 2003, at 6:09, James F. Hranicky wrote:
Since I’m griping, I’m also volunteering, so if anyone has pointers
I’d like
to hear them, otherwise, I’ll add RDoc comments to the C files as per
Gavin’s
suggestion.
I think you’re double posting to ruby-talk.
I’m not sure #open documentation belongs in #initialize. X#initialize
documentation shows up with X.new in the RDoc.
Lemme see…
Well, it appears that open is an alias for new in (UNIX)?Socket (and
therefore UNIXServer), so you are right. I dunno how it’s done,
though; ‘grep open *.c’ is singularly uninstructive.
Gavin
···
On Friday, December 12, 2003, 12:21:42 AM, James wrote:
On Thu, 11 Dec 2003 22:13:10 +0900 > “James F. Hranicky” jfh@cise.ufl.edu wrote:
/*
- Open a UNIX domain socket, e.g.:
- s = UNIXServer.open(“/tmp/sock”)
- UNIXServer.open(“/tmp/sock”) { |s| n = s.accept; n.puts(“you connected!”) }
*/
but as there is no corresponding rb_define_method() entry for UNIXServer.open,
it doesn’t show up.
Any pointers on where this should go?
smack duhhh…
This, and the doc for UNIXServer.new, should go in the initialize doc, right?
KO…let me know when to start back up.
Jim
···
On Fri, 12 Dec 2003 00:07:28 +0900 Dave Thomas dave@pragprog.com wrote:
On Dec 11, 2003, at 6:09, James F. Hranicky wrote:
Since I’m griping, I’m also volunteering, so if anyone has pointers
I’d like
to hear them, otherwise, I’ll add RDoc comments to the C files as per
Gavin’s
suggestion.
Hold off for just a week or two: RDoc might change just slightly as I
add ri integration. I’ve got the basics working, but I want to play a
bit before releasing.
In the meantime, I assume you’ve looked at
http://www.rubycentral.com/book/lib_network.html
Cheers
Dave
···
On Dec 11, 2003, at 9:15, James F. Hranicky wrote:
KO…let me know when to start back up.
Ack! I guess I haven’t run through Pickaxe in a while ( I know, bad
Jim…:-> ).
Any chance the info there could be moved into the 1.6 reference? As good
as the Pickaxe is, sometimes I just want a quick reference a la the 1.4.6
ref.
I’m probably opening up a big/old can of worms, right now it seems that
there are several sources of documentation for Ruby, all with different
areas covered. What is the ultimate vision for ruby docs? rd? ri? rdoc?
ruby-doc.org? pickaxe? The only thing php or perl have over Ruby IMO is
their docs are standardized: perldoc blah (even man blah…yay!),
or PHP: PHP Manual - Manual .
If I’m travleling over ground recently covered, please let me know. As a
sysadmin, I move from project to project, and I haven’t gotten to program
in Ruby or follow the mailing list carefully for a while, so I may be out
of touch.
Whatever the ultimate vision, I’m more than happy to help out.
Jim
···
On Fri, 12 Dec 2003 02:14:43 +0900 Dave Thomas dave@pragprog.com wrote:
On Dec 11, 2003, at 9:15, James F. Hranicky wrote:
KO…let me know when to start back up.
In the meantime, I assume you’ve looked at
http://www.rubycentral.com/book/lib_network.html
The vision I’m personally moving towards is RDoc/ri integration. RDoc
is convenient for writing internal documentation, and folks are already
adding it to the standard library. Within a couple of weeks, I’ll have
it integrated with ri, so you’ll be able to pull up any RDoc’d
documentation using ri (or something very similar to ri). For example,
saying
ri Socket
will list all the classes and modules that contain the word Socket in
their name, and
ri accept
will show you all the ‘accept’ methods that RDoc knows about. As this
is part of RDoc, and as RDoc is now included in Ruby core, this should
shortly be available pretty much universally.
Cheers
Dave
···
On Dec 11, 2003, at 11:50, James F. Hranicky wrote:
I’m probably opening up a big/old can of worms, right now it seems that
there are several sources of documentation for Ruby, all with different
areas covered. What is the ultimate vision for ruby docs? rd? ri? rdoc?
ruby-doc.org? pickaxe? The only thing php or perl have over Ruby IMO is
their docs are standardized: perldoc blah (even man blah…yay!),
or http://www.php.net/manual/en .
KO…let me know when to start back up.
In the meantime, I assume you’ve looked at
http://www.rubycentral.com/book/lib_network.html
Ack! I guess I haven’t run through Pickaxe in a while ( I know, bad
Jim…:->> ).
Any chance the info there could be moved into the 1.6 reference? As good
as the Pickaxe is, sometimes I just want a quick reference a la the 1.4.6
ref.
I’m probably opening up a big/old can of worms, right now it seems that
there are several sources of documentation for Ruby, all with different
areas covered. What is the ultimate vision for ruby docs? rd? ri? rdoc?
ruby-doc.org? pickaxe? The only thing php or perl have over Ruby IMO is
their docs are standardized: perldoc blah (even man blah…yay!),
or http://www.php.net/manual/en .
- rd is being used less and less.
- RDoc is being used more and more. A good practice for library authors
is to make the RDoc of their library viewable online, e.g.
http://extensions.rubyforge.org
- ri does built-in classes only, but is great at what it does
(http://rjay.roubyforge.org is an alpha attempt to add stdlib doc to
it)
- ruby-doc.org has several evolving aims, and will always collect
available Ruby documentation, as well as endeavouring to create it.
The stdlib documentation is a good example.
- Pickaxe: I presume you’re talking about updates. We’ll have to wait
and see.
The ultimate vision, for me, is
- RDoc being used everywhere
- ri giving quick access to RDoc info
- RubyGems simplifying access to the documentation for all your
installed packages
- ruby-doc.org completely documenting the standard library
- ruby-doc.org collecting all other documentation and providing a
breeding ground for original content
Although there are 5 points there, they don’t overlap (too much).
Whatever the ultimate vision, I’m more than happy to help out.
Excellent. I don’t know why Dave’s new work on RDoc means you
shouldn’t continue with Socket and OpenSSL, but since it’s in C it
could be a curly one. If you have a favourite library (Ruby-lang)
that isn’t currently documented, you could start there. If you want
an easier job, there are some libraries done in RD that need
conversion to RDoc.
Cheers,
Gavin
···
On Friday, December 12, 2003, 4:50:15 AM, James wrote:
On Fri, 12 Dec 2003 02:14:43 +0900 > Dave Thomas dave@pragprog.com wrote:
On Dec 11, 2003, at 9:15, James F. Hranicky wrote:
Sounds awesome. Thanks Dave.
Gavin
···
On Friday, December 12, 2003, 5:20:12 AM, Dave wrote:
On Dec 11, 2003, at 11:50, James F. Hranicky wrote:
I’m probably opening up a big/old can of worms, right now it seems that
there are several sources of documentation for Ruby, all with different
areas covered. What is the ultimate vision for ruby docs? rd? ri? rdoc?
ruby-doc.org? pickaxe? The only thing php or perl have over Ruby IMO is
their docs are standardized: perldoc blah (even man blah…yay!),
or http://www.php.net/manual/en .
The vision I’m personally moving towards is RDoc/ri integration. RDoc
is convenient for writing internal documentation, and folks are already
adding it to the standard library. Within a couple of weeks, I’ll have
it integrated with ri, so you’ll be able to pull up any RDoc’d
documentation using ri (or something very similar to ri). For example,
saying
ri Socket
will list all the classes and modules that contain the word Socket in
their name, and
ri accept
will show you all the ‘accept’ methods that RDoc knows about. As this
is part of RDoc, and as RDoc is now included in Ruby core, this should
shortly be available pretty much universally.
Because I may need to extend RDoc’s markup slightly to help it get more
information out of the C source. At the moment there’s no way of giving
meaningful names to method parameters, for example.
The timeline is first to get RDoc and ri integrated, and then to add
RDoc comments to one of the built-in classes (perhaps Array) and to see
what issues come up. Once I’ve worked the the majority of the problems,
I’ll then release it and ask for help, initially integrating the
existing ri documentation into the standard core Ruby files. Once
that’s done, we can turn our attention to the libraries.
Cheers
Dave
···
On Dec 11, 2003, at 15:57, Gavin Sinclair wrote:
Excellent. I don’t know why Dave’s new work on RDoc means you
shouldn’t continue with Socket and OpenSSL, but since it’s in C it
could be a curly one.
If one wanted to spent some time documenting a library or extension (one’s
own, or someone else’s), where would be a good place to look for
documentation on RDoc, and any documentation conventions to be followed?
…
snip
…
Excellent. I don’t know why Dave’s new work on RDoc means you
shouldn’t continue with Socket and OpenSSL, but since it’s in C it
could be a curly one. If you have a favourite library (Ruby-lang)
that isn’t currently documented, you could start there. If you want
an easier job, there are some libraries done in RD that need
conversion to RDoc.
Cheers,
Gavin
Derek Lewis
···
On Fri, 12 Dec 2003, Gavin Sinclair wrote:
===================================================================
Java Web-Application Developer
Email : email@lewisd.com
Cellular : 604.312.2846
Website : http://www.lewisd.com
“If you’ve got a 5000-line JSP page that has “all in one” support
for three input forms and four follow-up screens, all controlled
by “if” statements in scriptlets, well … please don’t show it
to me :-). Its almost dinner time, and I don’t want to lose my
appetite :-).”
- Craig R. McClanahan
For Ruby libraries, you could just have a look at RDoc’s README for
information on how to use it. As for conventions, they’ll be coming
along shortly. I know Gavin’s done some work on the standard library,
but that might have to change a tad if we want to make it work nicely
with ‘ri’ in future. (For example, file-level comments are not
accessible through ri, as files don’t have any meaning at that level.)
Frankly I don’t know the details right now: I’m still learning.
Cheers
Dave
···
On Dec 11, 2003, at 16:36, Derek Lewis wrote:
If one wanted to spent some time documenting a library or extension
(one’s
own, or someone else’s), where would be a good place to look for
documentation on RDoc, and any documentation conventions to be
followed?