Velocity Reviews - Computer Hardware Reviews

Velocity Reviews > Newsgroups > Programming > Ruby > Builtins RDoc tarball?

Reply
Thread Tools

Builtins RDoc tarball?

 
 
Gavin Sinclair
Guest
Posts: n/a
 
      02-18-2004
> James Britt wrote:

>
> Try here:
> http://www.ruby-doc.org/downloads
>
> But, note one and all, that the preferred way to get these files is to
> grab the actual Ruby source and run rdoc.



And then to go to http://www.rubygarden.org/ruby?Onlin...entationIssues
to record any comments you have about the quality of the documentation!
Getting this stuff done is an evolutionary process, which can be sped up
greatly by simple feedback saying "this needs to be done".

Gavin




 
Reply With Quote
 
 
 
 
Gavin Kistner
Guest
Posts: n/a
 
      02-18-2004
James Britt wrote:
> Try here:
> http://www.ruby-doc.org/downloads


Am I missing somewhere in there which has the builtin (aka Core API)
library rdoc? 'cause I don't see it.


I'm repeatedly failing to find this data on my own. If I do:

rdoc time.c

in the source directory, I get a listing of all of Time's methods, but
none of the documentation for those methods which is present in:
http://www.ruby-doc.org/docs/rdoc/1.9/classes/Time.html

Indeed, none of the 'time*' files that I can find in the source
directory seem to generate such output. (The above url lists time.c and
lib/time.rb as the location files, but rdoc'ing both of those together
doesn't get me descriptions of the methods.)


In fact...here we go:

The start of
http://www.ruby-doc.org/docs/rdoc/1....e.html#M000185
says:
"Creates a new time object with the value given by ..."

But when I search for that phrase in the entire source directory, I get
nothing:

root# grep -r 'a new time object' /usr/local/src/ruby-1.8.1/*
root#


So the question remains...where is ruby-doc.org getting its information?
A custom version of the source with all comments included?
Customized files meticulously self-documented?

--
(-, /\ \/ / /\/
 
Reply With Quote
 
 
 
 
Dave Thomas
Guest
Posts: n/a
 
      02-18-2004

On Feb 18, 2004, at 8:39, Gavin Kistner wrote:
> I'm repeatedly failing to find this data on my own. If I do:
>
> rdoc time.c
>
> in the source directory, I get a listing of all of Time's methods, but
> none of the documentation for those methods which is present in:
> http://www.ruby-doc.org/docs/rdoc/1.9/classes/Time.html


Look in the source file for time.c: can you see comments containing the
documentation in front of the C methods that implement the class's
public interface? If not, you're probably looking at an old version of
the source.


Cheers

Dave



 
Reply With Quote
 
Gavin Kistner
Guest
Posts: n/a
 
      02-18-2004
On Feb 18, 2004, at 8:32 AM, Dave Thomas wrote:
> Look in the source file for time.c: can you see comments containing
> the documentation in front of the C methods that implement the class's
> public interface? If not, you're probably looking at an old version of
> the source.


That was the case, where 'old' is 1.8.1, and not a 1.9 snapshot.

Getting 1.9 for rdoc building did the trick. (Or rather, I can see the
methods of Time now. I'm still fighting to find out what file(s) are
causing rdoc to crash when writing the output) Thanks


While I've got you here...is there a way to get rdoc to document
multiple call sequences for a method in a .rb file? I tried mimicking
the style seen in time.c:

/*
* call-seq:
* Time.at( aTime ) => time
* Time.at( seconds [, microseconds] ) => time

But putting that same sort of code in myfile.rb:

# call-seq:
# MutableTime.foo( a )
# MutableTime.foo( b )

...failed to produce the same results.



 
Reply With Quote
 
Gavin Kistner
Guest
Posts: n/a
 
      02-18-2004
Gavin Kistner wrote:
> Getting 1.9 for rdoc building did the trick. (Or rather, I can see the
> methods of Time now. I'm still fighting to find out what file(s) are
> causing rdoc to crash when writing the output) Thanks


Amazingly, I'm still fighting this. Here's the latest output (using rdoc
from 1.8.1 on the latest snapshot sources):

ruby-snapshot_20040218] root# rdoc --op rdoc *.c *.rb

array.c:
[...]
instruby.rb: .....
mdoc2man.rb: c....
mkconfig.rb:
rubytest.rb:
runruby.rb:
Generating HTML...
/usr/local/lib/ruby/1.8/rdoc/code_objects.rb:334:in `find_symbol'
*** malloc: vm_allocate(size=214748364 failed (error code=3)
*** malloc[1195]: error: Can't allocate region
*** malloc: vm_allocate(size=214748364 failed (error code=3)
*** malloc[1195]: error: Can't allocate region
: undefined method `find_local_symbol' for #<RDoc::AnyMethod:0x3cb118>
(NoMethodError)
from
/usr/local/lib/ruby/1.8/rdoc/generators/html_generator.rb:1015:in
`find_symbol'
from
/usr/local/lib/ruby/1.8/rdoc/generators/html_generator.rb:116:in
`handle_special_CROSSREF'
from
/usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:226:in `send'
from
/usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:226:in
`convert_special'
from
/usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:223:in
`each_name_of'
from
/usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/inline.rb:32:in `each'
from
/usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/inline.rb:32:in
`each_name_of'
from
/usr/local/lib/ruby/1.8/rdoc/markup/simple_markup/to_html.rb:223:in
`convert_special'
... 24 levels...
from
/usr/local/lib/ruby/1.8/rdoc/generators/html_generator.rb:1168:in
`generate_html'
from
/usr/local/lib/ruby/1.8/rdoc/generators/html_generator.rb:1092:in `generate'
from /usr/local/lib/ruby/1.8/rdoc/rdoc.rb:210:in `document'
from /usr/local/bin/rdoc:63
 
Reply With Quote
 
Gavin Sinclair
Guest
Posts: n/a
 
      02-18-2004
On Thursday, February 19, 2004, 3:02:29 AM, Gavin wrote:

> That was the case, where 'old' is 1.8.1, and not a 1.9 snapshot.


Yes, unfortunately 1.8.1 just missed the boat on the core API documentation
front. Still, that means it should be tried and tested in time for
1.8.2.

> Getting 1.9 for rdoc building did the trick. (Or rather, I can see the
> methods of Time now. I'm still fighting to find out what file(s) are
> causing rdoc to crash when writing the output) Thanks


Thanks for the persistence. We need to shake these problems out.


> While I've got you here...is there a way to get rdoc to document
> multiple call sequences for a method in a .rb file? I tried mimicking
> the style seen in time.c:


> /*
> * call-seq:
> * Time.at( aTime ) => time
> * Time.at( seconds [, microseconds] ) => time


> But putting that same sort of code in myfile.rb:


> # call-seq:
> # MutableTime.foo( a )
> # MutableTime.foo( b )


> ...failed to produce the same results.


No, it's a C workaround. RDoc can't parse an adequate method header
from C code, because default parameters are done indirectly, and maybe
other reasons.

I'd rather all methods look the same in RDoc output, and that the
'sameness' be modelled on the way Ruby is parsed. I can see the
benefit in the case of Time.at, above, but...

(OTOH, I'm grateful that RDoc can understand C at all...)

Cheers,
Gavin



 
Reply With Quote
 
Gavin Sinclair
Guest
Posts: n/a
 
      02-18-2004
On Thursday, February 19, 2004, 3:39:56 AM, Gavin wrote:

> Gavin Kistner wrote:
>> Getting 1.9 for rdoc building did the trick. (Or rather, I can see the
>> methods of Time now. I'm still fighting to find out what file(s) are
>> causing rdoc to crash when writing the output) Thanks


> Amazingly, I'm still fighting this. Here's the latest output (using rdoc
> from 1.8.1 on the latest snapshot sources):


> [errors snipped]


Hmmmm, ugly. I'll let Dave read the entrails, but I'll just suggest
that you use the latest RDoc version. Yes, that means building Ruby
all over again, unless you roll your own RDoc installer

There's been significant work on the software as well as the
documentation since 1.8.1, I believe.

Gavin



 
Reply With Quote
 
Dave Thomas
Guest
Posts: n/a
 
      02-18-2004

On Feb 18, 2004, at 10:02, Gavin Kistner wrote:
> That was the case, where 'old' is 1.8.1, and not a 1.9 snapshot.
>


The 1.8 branch in CVS has them too.

> While I've got you here...is there a way to get rdoc to document
> multiple call sequences for a method in a .rb file? I tried mimicking
> the style seen in time.c:
>


Not currently. Is that something that would be generally useful?

Cheers

Dave



 
Reply With Quote
 
Dave Thomas
Guest
Posts: n/a
 
      02-18-2004

On Feb 18, 2004, at 10:39, Gavin Kistner wrote:
> ruby-snapshot_20040218] root# rdoc --op rdoc *.c *.rb
>
> array.c:
> [...]
> instruby.rb: .....
> mdoc2man.rb: c....
> mkconfig.rb:
> rubytest.rb:
> runruby.rb:
> Generating HTML...
> /usr/local/lib/ruby/1.8/rdoc/code_objects.rb:334:in `find_symbol'
> *** malloc: vm_allocate(size=214748364 failed (error code=3)
> *** malloc[1195]: error: Can't allocate region
> *** malloc: vm_allocate(size=214748364 failed (error code=3)
> *** malloc[1195]: error: Can't allocate region


I don't know about the rest of your problems, but the above seem to me
to be an interpreter problem.

In the meantime, you probably don't want to document the .rb files in
the main ruby directory. Just type

rdoc --op rdoc

and let it work out what to document.


Cheers


Dave



 
Reply With Quote
 
Gavin Kistner
Guest
Posts: n/a
 
      02-18-2004
On Feb 18, 2004, at 10:18 AM, Dave Thomas wrote:
> In the meantime, you probably don't want to document the .rb files in
> the main ruby directory. Just type
>
> rdoc --op rdoc
>
> and let it work out what to document.


Trying that takes 20 minutes a pop and has failed in the past. I was
attempting to pare down and see if it was a particular file that was
borked.

Anyhow, I'm now following Mr. Sinclair's advice and going to rebuild
Ruby with the latest stable snapshot, and see if the rdoc provided by
that fares any better.

(The same error occurred when I ran it on just *.c in the main
directory, FWIW.)

--
(-, /\ \/ / /\/



 
Reply With Quote
 
 
 
Reply

Thread Tools

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off
Trackbacks are On
Pingbacks are On
Refbacks are Off


Similar Threads
Thread Thread Starter Forum Replies Last Post
How to use rdoc parsers outside of rdoc? Paul Van Delst Ruby 0 07-27-2006 07:18 PM
rdoc: how to add readme.rdoc as index.html? Iwan van der Kleyn Ruby 1 04-26-2005 12:37 PM
[RDOC] Using a template causes rdoc not to document some classes Daniel Berger Ruby 1 11-02-2004 08:23 PM
rdoc bug (and rdoc bug tracker site is down) Brian Schröder Ruby 5 09-18-2004 02:08 PM
rdoc: how to generate rdoc & ri documentation of standard library? Andreas Schwarz Ruby 6 01-01-2004 03:09 AM



Advertisments