Argh! more undocumented mysteries: to_yaml

ruby-talk
1

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml. Seems pretty obvious what to expect here, which would seem to account for the total lack of documentation in each of the gazillion instances of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
        from (irb):10

Can someone explain what just happened?

Thanks!

t.

···

from :0

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog) << sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

2

I'm beginner to but I understand it. You cannot use to_yaml for Array,
because there's no method to_yaml for Array. Try to read about
Object#to_yaml in Ruby Documentation.

···

2008/3/16, Tom Cloyd <tomcloyd@comcast.net>:

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml.
Seems pretty obvious what to expect here, which would seem to account
for the total lack of documentation in each of the gazillion instances
of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
        from (irb):10
        from :0

Can someone explain what just happened?

Thanks!

t.

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

3

Yes. to_yaml is defined in the yaml.rb file, so you need to require it before
using to_yaml:

irb(main):001:0> require 'yaml'
=> true
irb(main):002:0> [2,3,4,5, 'abc'].to_yaml
=> "--- \n- 2\n- 3\n- 4\n- 5\n- abc\n"

How are you supposed to know that to_yaml is not in ruby core but in the
standard library? I don't really know. When I started using ruby some years
ago, I downloaded a version of the rdoc documentation from
www.ruby-doc.org which only included documentation for the core classes (that
is, those you can use without need to require some files), while documentation
for the standard library was in a separate package. Unfortunately, the
documentation you can find nowadays includes both core and standard library.
This has the very unpleasant side effect of displaying together methods which
come from the core classes and methods which come from files in the standard
library (which should be required before using such methods). At any rate, at
the top of the page, just below the name of the class, there's a list of the
files which have been used to generate the documentation for the class. If a
method listed in the documentation doesn't seem to exist, try requiring those
files. In the specific case of Object#to_yaml, this doesn't work, though,
since the file where the method is defined, lib/yaml/rubytypes.rb, can't be
required directly, but only requiring 'yaml'. It can give you a hint.

Stefano

···

On Sunday 16 March 2008, Tom Cloyd wrote:

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml.
Seems pretty obvious what to expect here, which would seem to account
for the total lack of documentation in each of the gazillion instances
of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
        from (irb):10
        from :0

Can someone explain what just happened?

Thanks!

t.

4

Tom Cloyd wrote:

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml. Seems pretty obvious what to expect here, which would seem to account for the total lack of documentation in each of the gazillion instances of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
       from (irb):10
       from :0

Can someone explain what just happened?

Thanks!

t.

irb(main):005:0> [2,3,4].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 3, 4]:Array
         from (irb):5
irb(main):006:0> require "yaml"
=> true
irb(main):008:0> [2,3,4].to_yaml
=> "--- \n- 2\n- 3\n- 4\n"

See also:
http://ruby-doc.org/core/classes/YAML.html

--Phillip Gawlowski

···

from :0

5

Tom:

Could you tell us just where you found the description of Object#to_yaml.

As others have explained, to_yaml is not a built-in method. It is added when you require the yaml library. So, if a piece of documentation is out there that fails to make it clear that this library must be loaded before to_yaml is called, then that documentation needs to be fixed.

As others have also pointed out, once the library is loaded, you can indeed invoke to_yaml on arrays, hashes, and so on.

Regards

Dave Thomas

···

On Mar 16, 2008, at 8:56 AM, Tom Cloyd wrote:

I'm exploring the wonders of the Object class, and I see Object#to_yaml. Seems pretty obvious what to expect here, which would seem to account for the total lack of documentation in each of the gazillion instances of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
      from (irb):10
      from :0

Can someone explain what just happened?

6

Documentation? WHAT documentation? Please read my email.

Also, replicate my example in irb - with any object you wish. (I tried Array, Fixnum, Float - all raise the same error)

Finally, consider this statement from the general documentation for the Class Object at http://www.ruby-doc.org/core/:
"Object <http://www.ruby-doc.org/core/classes/Object.html&gt; is the parent class <class Object - RDoc Documentation; of all classes in Ruby. Its methods <class Object - RDoc Documentation; are therefore available to all objects unless explicitly overridden."

My problem remains as I stated it.

Thanks for your response, in any case. I will hold out for the possibility that with a little more examination you'll see what I have so far missed - the reason for this problem.

Thanks!

t.

Mateusz Tybura wrote:

···

I'm beginner to but I understand it. You cannot use to_yaml for Array,
because there's no method to_yaml for Array. Try to read about
Object#to_yaml in Ruby Documentation.

2008/3/16, Tom Cloyd <tomcloyd@comcast.net>:
  

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml.
Seems pretty obvious what to expect here, which would seem to account
for the total lack of documentation in each of the gazillion instances
of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
        from (irb):10
        from :0

Can someone explain what just happened?

Thanks!

t.

--
    
--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog) << sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

7

Stefano Crocco wrote:

How are you supposed to know that to_yaml is not in ruby core but in the
standard library? I don't really know. When I started using ruby some years
ago, I downloaded a version of the rdoc documentation from
www.ruby-doc.org which only included documentation for the core classes (that
is, those you can use without need to require some files), while documentation for the standard library was in a separate package. Unfortunately, the
documentation you can find nowadays includes both core and standard library.

The ri command shows the documentation for the merged core and standard libraries. It's sad but it's true. However, it isn't hard to find out what's the the core and what isn't.

This link Documentation has a link to the top-level www.ruby-doc.org as well as individual links to the core and standard API sections of ruby-doc.

When I go to www.ruby-doc.org right now, the documentation for the Core API is clearly separated from the documentation for the Standard API. The yaml library is documented in the Standard API documentation.

When I view the online (first edition) version of _Programming_Ruby_ (Programming Ruby: The Pragmatic Programmer's Guide) the core API is documented in the "Built in Classes and Methods" chapter. The Standard library is documented in the "Standard Library" chapter. The yaml library isn't documented in that book because it didn't exist when the first edition was written. The 2nd edition (pay for) includes yaml in the Standard Library chapter. There is also a short tutorial about yaml in the marshalling chapter.

···

--
RMagick: http://rmagick.rubyforge.org/
RMagick 2: http://rmagick.rubyforge.org/rmagick2.html

8

Stefano Crocco wrote:

···

On Sunday 16 March 2008, Tom Cloyd wrote:
  

Beginner woes, here, no doubt, but woes nevertheless.

I'm exploring the wonders of the Object class, and I see Object#to_yaml.
Seems pretty obvious what to expect here, which would seem to account
for the total lack of documentation in each of the gazillion instances
of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
        from (irb):10
        from :0

Can someone explain what just happened?

Thanks!

t.
    
Yes. to_yaml is defined in the yaml.rb file, so you need to require it before using to_yaml:

irb(main):001:0> require 'yaml'
=> true
irb(main):002:0> [2,3,4,5, 'abc'].to_yaml
=> "--- \n- 2\n- 3\n- 4\n- 5\n- abc\n"

How are you supposed to know that to_yaml is not in ruby core but in the
standard library? I don't really know. When I started using ruby some years
ago, I downloaded a version of the rdoc documentation from
www.ruby-doc.org which only included documentation for the core classes (that
is, those you can use without need to require some files), while documentation for the standard library was in a separate package. Unfortunately, the
documentation you can find nowadays includes both core and standard library.
This has the very unpleasant side effect of displaying together methods which come from the core classes and methods which come from files in the standard
library (which should be required before using such methods). At any rate, at the top of the page, just below the name of the class, there's a list of the
files which have been used to generate the documentation for the class. If a
method listed in the documentation doesn't seem to exist, try requiring those files. In the specific case of Object#to_yaml, this doesn't work, though,
since the file where the method is defined, lib/yaml/rubytypes.rb, can't be
required directly, but only requiring 'yaml'. It can give you a hint.

Stefano

Interesting. I have NO idea how I might have found this out, but I will make a note to try requiring something if it doesn't seem to be available. I fault myself for not thinking of that!

t.

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog) << sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

9

Dave Thomas wrote:

I'm exploring the wonders of the Object class, and I see Object#to_yaml. Seems pretty obvious what to expect here, which would seem to account for the total lack of documentation in each of the gazillion instances of this method which appear in core library. Still, let's test it...

irb(main):010:0> [2,5,3,6,'abc'].to_yaml
NoMethodError: undefined method `to_yaml' for [2, 5, 3, 6, "abc"]:Array
      from (irb):10
      from :0

Can someone explain what just happened?

Tom:

Could you tell us just where you found the description of Object#to_yaml.

As others have explained, to_yaml is not a built-in method. It is added when you require the yaml library. So, if a piece of documentation is out there that fails to make it clear that this library must be loaded before to_yaml is called, then that documentation needs to be fixed.

As others have also pointed out, once the library is loaded, you can indeed invoke to_yaml on arrays, hashes, and so on.

Regards

Dave Thomas

OK...now THIS is the reaction I was really looking for, which is why I provided the documentation I did in my first two emails. From my point of view, and as your response here would seem to support, beginners like me can, in exploring the interface to Ruby (part of which is its available documentation) find glitches which those of you with expert knowledge all too easily miss. We are, in fact, a uniquely valuable resource, I would hope. I'm trying to be, in any case.

So...here's the path to the documentation (can't give an specific URL, due to use of frames):
1. go to RDoc Documentation
2. in the middle panel, select the Object class.
3. scroll down to Methods, and find the to_yaml method
4. clicking on that, you'll see there's no documentation. So, go back to the top of the Object's page, and see the sentence I noted in my second email: " Object is the parent class of all classes in Ruby. Its methods are therefore available to all objects unless explicitly overridden."

To my mind, there is nothing here that suggests that I must "require" anything to get access to this method. Hence my (enduring) bewilderment. Were I more knowledgeable about object inspection, I'd have seen why I got the irb error I did, but still would not have know why irb blocks this method.

I hope this helps the cause, and thanks for your interest.

t.

···

On Mar 16, 2008, at 8:56 AM, Tom Cloyd wrote:

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog) << sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

10

Stefano Crocco wrote:

How are you supposed to know that to_yaml is not in ruby core but in the
standard library? I don't really know.

Yes; it is a good question.

Sadly, the rdoc/ri tool is brain-dead about mix-ins.

  When I started using ruby some years

ago, I downloaded a version of the rdoc documentation from
www.ruby-doc.org which only included documentation for the core classes (that
is, those you can use without need to require some files), while documentation for the standard library was in a separate package. Unfortunately, the
documentation you can find nowadays includes both core and standard library.

It appears that the Ruby source code includes .document files that direct which source files should be processed by rdoc

What has happened is that there is no clear separation in the rdoc settings between core classes and standard lib.

The Yaml source files get pulled in by rdoc along with several other std-lib files, as well as core files. Rdoc stores what it finds and emits an aggregate result. Since yaml alters core classes, the resulting rdoc falsely shows Array, String, etc as having to_yaml methods as if they were built into the original code. There is no indication that those methods only exist if YAML is included.

This has the very unpleasant side effect of displaying together methods which come from the core classes and methods which come from files in the standard
library (which should be required before using such methods). At any rate, at the top of the page, just below the name of the class, there's a list of the
files which have been used to generate the documentation for the class. If a
method listed in the documentation doesn't seem to exist, try requiring those files.

A useful tip, but a sad indication of rdoc's failings with mix-ins.

···

--
James Britt

"Inside every large system there's a small system trying to get out".
    - Chet Hendrickson

11

Tom Cloyd wrote:

Documentation? WHAT documentation? Please read my email.

Also, replicate my example in irb - with any object you wish. (I tried Array, Fixnum, Float - all raise the same error)

Finally, consider this statement from the general documentation for the Class Object at http://www.ruby-doc.org/core/:
"Object <http://www.ruby-doc.org/core/classes/Object.html&gt; is the parent class <class Object - RDoc Documentation; of all classes in Ruby. Its methods <class Object - RDoc Documentation; are therefore available to all objects unless explicitly overridden."

My problem remains as I stated it.

Thanks for your response, in any case. I will hold out for the possibility that with a little more examination you'll see what I have so far missed - the reason for this problem.

You don't use the tools Ruby/irb gives you:
>> Object.methods.sort
=> ["<", "<=", "<=>", "==", "===", "=~", ">", ">=", "__id__", "__send__", "allocate", "ancestors", "autoload", "autoload?", "class", "class_eval", "class_variable_defined?", "class_variables", "clone", "const_defined?", "const_get", "const_missing", "const_set", "constants", "display", "dup", "eql?", "equal?", "extend"
, "freeze", "frozen?", "hash", "id", "include?", "included_modules", "inspect","instance_eval", "instance_method", "instance_methods", "instance_of?", "instance_variable_defined?", "instance_variable_get", "instance_variable_set", "instance_variables", "is_a?", "kind_of?", "method", "method_defined?", "methods", "module_eval", "name", "new", "nil?", "object_id", "private_class_method", "private_instance_methods", "private_method_defined?", "private_methods", "protected_instance_methods", "protected_method_defined?", "protected_methods", "public_class_method", "public_instance_methods", "public_method_defined?", "public_methods", "respond_to?", "send", "singleton_methods", "superclass", "taint", "tainted?", "to_a", "to_s", "type", "untaint"]

As you can see, the method is not, by default, defined You already know that the documentation leaves some things desirable, so start using Google, or Ruby's capabilities of inspection, to narrow down your mistakes/errors and do some troubleshooting. You'll need these skills when writing applications, anyway.

And as an MS/MA you certainly learned research skills at college. If they've atrophied, now's a good chance to resurrect them, no?

-- Phillip Gawlowski

12

Just to follow up on my previous email...

It's also possible you saw Object#to_yaml if you're using the 'ri' utility and you have the yaml library installed on your local machine. ri lists all the methods that can possibly appear in a class, and (somewhat stupidly) fails to differential between those that are built in and those that can be added. (I say somewhat stupidly because it was my fault :).

Regards

Dave Thomas

···

On Mar 16, 2008, at 9:18 AM, Tom Cloyd wrote:

I will hold out for the possibility that with a little more examination you'll see what I have so far missed - the reason for this problem.

13

As far as I can see, the links to the 'Core documentation' on both www.ruby-
doc.org and Documentation point to the same
documentation, which sadly contains both the core and the standard library. As
you say, the standard library is also documented in its own section, which is
much more organized, and easy to use.

Stefano

···

On Sunday 16 March 2008, Tim Hunter wrote:

Stefano Crocco wrote:
> How are you supposed to know that to_yaml is not in ruby core but in the
> standard library? I don't really know. When I started using ruby some
> years ago, I downloaded a version of the rdoc documentation from
> www.ruby-doc.org which only included documentation for the core classes
> (that is, those you can use without need to require some files), while
> documentation for the standard library was in a separate package.
> Unfortunately, the documentation you can find nowadays includes both core
> and standard library.

The ri command shows the documentation for the merged core and standard
libraries. It's sad but it's true. However, it isn't hard to find out
what's the the core and what isn't.

This link Documentation has a link to the
top-level www.ruby-doc.org as well as individual links to the core and
standard API sections of ruby-doc.

When I go to www.ruby-doc.org right now, the documentation for the Core
API is clearly separated from the documentation for the Standard API.
The yaml library is documented in the Standard API documentation.

14

James:

When you use all this stuff to build ruby-doc, why not override the defaults so you can present the information differently?

Regards

Dave Thomas

···

On Mar 16, 2008, at 11:47 AM, James Britt wrote:

It appears that the Ruby source code includes .document files that direct which source files should be processed by rdoc

What has happened is that there is no clear separation in the rdoc settings between core classes and standard lib.

The Yaml source files get pulled in by rdoc along with several other std-lib files, as well as core files. Rdoc stores what it finds and emits an aggregate result. Since yaml alters core classes, the resulting rdoc falsely shows Array, String, etc as having to_yaml methods as if they were built into the original code. There is no indication that those methods only exist if YAML is included.

15

Phillip Gawlowski wrote:

Tom Cloyd wrote:

Documentation? WHAT documentation? Please read my email.

Also, replicate my example in irb - with any object you wish. (I tried Array, Fixnum, Float - all raise the same error)

Finally, consider this statement from the general documentation for the Class Object at http://www.ruby-doc.org/core/:
"Object <http://www.ruby-doc.org/core/classes/Object.html&gt; is the parent class <class Object - RDoc Documentation; of all classes in Ruby. Its methods <class Object - RDoc Documentation; are therefore available to all objects unless explicitly overridden."

My problem remains as I stated it.

Thanks for your response, in any case. I will hold out for the possibility that with a little more examination you'll see what I have so far missed - the reason for this problem.

You don't use the tools Ruby/irb gives you:
>> Object.methods.sort
=> ["<", "<=", "<=>", "==", "===", "=~", ">", ">=", "__id__", "__send__", "allocate", "ancestors", "autoload", "autoload?", "class", "class_eval", "class_variable_defined?", "class_variables", "clone", "const_defined?", "const_get", "const_missing", "const_set", "constants", "display", "dup", "eql?", "equal?", "extend"
, "freeze", "frozen?", "hash", "id", "include?", "included_modules", "inspect","instance_eval", "instance_method", "instance_methods", "instance_of?", "instance_variable_defined?", "instance_variable_get", "instance_variable_set", "instance_variables", "is_a?", "kind_of?", "method", "method_defined?", "methods", "module_eval", "name", "new", "nil?", "object_id", "private_class_method", "private_instance_methods", "private_method_defined?", "private_methods", "protected_instance_methods", "protected_method_defined?", "protected_methods", "public_class_method", "public_instance_methods", "public_method_defined?", "public_methods", "respond_to?", "send", "singleton_methods", "superclass", "taint", "tainted?", "to_a", "to_s", "type", "untaint"]

As you can see, the method is not, by default, defined You already know that the documentation leaves some things desirable, so start using Google, or Ruby's capabilities of inspection, to narrow down your mistakes/errors and do some troubleshooting. You'll need these skills when writing applications, anyway.

And as an MS/MA you certainly learned research skills at college. If they've atrophied, now's a good chance to resurrect them, no?

-- Phillip Gawlowski

Phillip, good research begins with careful observation - in this case, of the materials at hand. In my immediately previous email I pointed out that the ruby core documentation, for which I gave a reference, so you could check my accuracy (basic scholarly method), tells me that Object#to_yaml should be available to all object unless "explicitly overridden". I then present some cases where it isn't available. That contradiction is what I could not explain. I do not expect such a blatant error/omission/contradiction - or whatever - in the ruby core documentation. If I can't trust what it says about the root object of all objects, then what can I trust? That, to me, looks like a problem - and not exactly one I'd expect Google or some blog entry to solve.

Your ">> Object.methods.sort " tip is useful, as is the suggestion that I learn more of Ruby's self-inspection tools. I will pursue this. It didn't occur to me that irb would deny use of this method. That was clearly an erroneous assumption, howsoever reasonable it may have seemed at the time.

t.

···

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog) << sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

16

Dave Thomas wrote:

I will hold out for the possibility that with a little more examination you'll see what I have so far missed - the reason for this problem.

Just to follow up on my previous email...

It's also possible you saw Object#to_yaml if you're using the 'ri' utility and you have the yaml library installed on your local machine. ri lists all the methods that can possibly appear in a class, and (somewhat stupidly) fails to differential between those that are built in and those that can be added. (I say somewhat stupidly because it was my fault :).

Regards

Dave Thomas

Well, Dave, looks like we've found our culprit (heh heh). However, I simply cannot fault someone who's been such an asset to us all. I will try simply to remember that Ruby and its documentation is a work in progress, and that as my own cleverness grows, my expectations of Ruby's can gracefully diminish. Every weekend I spend with Ruby is increasingly informative, and this one is no exception. And...the good folks on this list are a major reason for my continuing education. Thanks to you all.

t.

···

On Mar 16, 2008, at 9:18 AM, Tom Cloyd wrote:

--

~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Tom Cloyd, MS MA, LMHC
Private practice Psychotherapist
Bellingham, Washington, U.S.A: (360) 920-1226
<< tc@tomcloyd.com >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog) << sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

17

Stefano Crocco wrote:

···

On Sunday 16 March 2008, Tim Hunter wrote:

The ri command shows the documentation for the merged core and standard
libraries. It's sad but it's true. However, it isn't hard to find out
what's the the core and what isn't.

This link Documentation has a link to the
top-level www.ruby-doc.org as well as individual links to the core and
standard API sections of ruby-doc.

When I go to www.ruby-doc.org right now, the documentation for the Core
API is clearly separated from the documentation for the Standard API.
The yaml library is documented in the Standard API documentation.

As far as I can see, the links to the 'Core documentation' on both www.ruby-
doc.org and Documentation point to the same documentation, which sadly contains both the core and the standard library. As you say, the standard library is also documented in its own section, which is much more organized, and easy to use.

So it does. Thanks for pointing this out. It would be nice if some talented Rubyist were to upgrade rdoc so that this didn't happen. Until then I'll have to refer to my paper documentation when my memory fails me. (Which it frequently does.)

--
RMagick: http://rmagick.rubyforge.org/
RMagick 2: http://rmagick.rubyforge.org/rmagick2.html

18

Dave Thomas wrote:

It appears that the Ruby source code includes .document files that direct which source files should be processed by rdoc

What has happened is that there is no clear separation in the rdoc settings between core classes and standard lib.

The Yaml source files get pulled in by rdoc along with several other std-lib files, as well as core files. Rdoc stores what it finds and emits an aggregate result. Since yaml alters core classes, the resulting rdoc falsely shows Array, String, etc as having to_yaml methods as if they were built into the original code. There is no indication that those methods only exist if YAML is included.

James:

When you use all this stuff to build ruby-doc, why not override the defaults so you can present the information differently?

I am looking into that.

It is not clear what would be a good approach to ensure that all the files get covered by rdoc, yet do not interfere with other files if they involve modifying other files, and still have proper "cluster" processing of sets of files that belong together (such as, say, the tk or REXML files).

One thought was to run rdoc over each file individually, and then reassembly the resulting pages. Somehow. The generation process is easy enough to automate. I'm unsure though that the resulting files are not going to lose some essential cohesion (aside from the main index a bulk rdoc pass creates).

Unfortunately, the conventional description for creating ri and rdoc for ruby, and the way the Ruby source code installation handles it, is to simply process the entire source folder. More and more files have been added to .document files, with the default ri and rdoc output showing, for example, to_yaml as a method of Array. So,

   $ ri Array

can be misleading.

Basically, what is now appearing on ruby-doc.org are the results of the canonical rdoc'ing of the Ruby source.

James

···

On Mar 16, 2008, at 11:47 AM, James Britt wrote:

Regards

Dave Thomas

--
James Britt

"Trying to port the desktop metaphor to the Web is like working
on how to fuel your car with hay because that is what horses eat."
    - Dare Obasanjo

19

Tom Cloyd wrote:

Phillip, good research begins with careful observation - in this case, of the materials at hand. In my immediately previous email I pointed out that the ruby core documentation, for which I gave a reference, so you could check my accuracy (basic scholarly method), tells me that Object#to_yaml should be available to all object unless "explicitly overridden". I then present some cases where it isn't available. That contradiction is what I could not explain. I do not expect such a blatant error/omission/contradiction - or whatever - in the ruby core documentation. If I can't trust what it says about the root object of all objects, then what can I trust? That, to me, looks like a problem - and not exactly one I'd expect Google or some blog entry to solve.

You do know, however, that the state of Ruby's documentation on the web is rather bad. Which creates faulty assumptions, as you've noticed. :wink:

And yes, something like this is something a blog entry (or, more generally speaking, a blog entry) can solve, since you more likely than not aren't the first person to have this problem.

Unfortunately, the only way to get a reasonably up-to-date documentation for Ruby is via Programming Ruby (and maybe The Ruby Programming Language), which also provides usage examples. The free edition of the Pickaxe is slightly out of date (as has been mentioned elsewhere).

The trick is, that you are standing on the shoulder of giants. Tapping into that, can make Ruby much more hassle free (and I've ran against a wall when using Ruby's documentation myself, hence my fondness for the Pickaxe).

-- Phillip Gawlowski

20

The main issue though is just that ruby-doc.org should only show core documentation in that section though, right?

Surely we could script that. What happens if we replace the .document files in lib/ and ext/ with empty files before we build the docs, or just erase those two directories before we build?

The standard library documentation is build by an altogether different process Gavin Kistner manages (or at least did), right?

I'm happy to help if I can. Just let me know if you need anything.

James Edward Gray II

···

On Mar 16, 2008, at 6:56 PM, James Britt wrote:

Unfortunately, the conventional description for creating ri and rdoc for ruby, and the way the Ruby source code installation handles it, is to simply process the entire source folder. More and more files have been added to .document files, with the default ri and rdoc output showing, for example, to_yaml as a method of Array. So,

$ ri Array

can be misleading.

Basically, what is now appearing on ruby-doc.org are the results of the canonical rdoc'ing of the Ruby source.