Argh! more undocumented mysteries: to_yaml

ruby-talk
21

/me applauds Tom Cloyd's graciousness. Seriously, it's good to see
someone with a genuine complaint being so positive.

Jeremy Henty

···

On 2008-03-16, Tom Cloyd <tomcloyd@comcast.net> wrote:

Dave Thomas wrote:

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 :).

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.

22

Phillip Gawlowski wrote:

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

Agreed - with all. And I own a copy of Pickaxe 2nd ed., in marvelous searchable PDF format (highly recommended). However, the to_yaml method is not documented in the discussion of the Object class - it's not reasonable to expect EVERYTHING to be covered, I'm sure.

An exhaustive search of the book reveals only that to_yaml_properties is discussed at one point, and in the context it appears to be related to the YAML standard library, BECAUSE a require is used, and what I was recently taught (on this list) is that core library doesn't have to be required, AND the online documentation says that to_yaml is core. With the information I have, at this point, I'm not clever enough to think my way out of this confusion.

Just wanted to make it clear that I did do a fair amount of due diligence before bringing the problem here.

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)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

23

James Gray 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.

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

James,

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

Oh yes! Right on-message. I'm delighted to see that this whole thread just may result in a better documentation process and product. I'm grateful that some of the first citizens of the ruby community are paying attention. Very grateful.

Experience and expert knowledge makes us blind. But I don't have that experience, so maybe, just maybe, my distress about this issue will make Ruby and its documentation more accessible for the rising tide of people newly interested in this wonderful language. I hope so. That'd be a huge payoff, relative to anything else I might possibly contribute to the community.

This whole matter reminds me of a virtuous practice from the other major technical involvement I have with computers: building websites. We are well advised, in that domain, to invite the naive to interface with our products, because they will show us design flaws we blindly fly right past. This procedure really works, and really does produce major improvements in our product and its utility to consumers.

Carry on...

t.

···

On Mar 16, 2008, at 6:56 PM, James Britt 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)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

24

Tom:

(page numbers below are for the printed copy)

Page 758 is the description of the YAML standard library.

Because it's a standard library, you know you need to use require (page 653). And the examples on the YAML page all show the use of require.

I hadn't realized you owned a copy of the book--if I had, I could have saved you time by pointing you at these pages.

Just to reiterate: to_yaml is not a method of the built-in Object class. That's why it doesn't appear in the documentation of object. When you do <rewquire 'yaml'>, that library _adds_ the method to object.

Dave Thomas

···

On Mar 16, 2008, at 11:37 AM, Tom Cloyd wrote:

Agreed - with all. And I own a copy of Pickaxe 2nd ed., in marvelous searchable PDF format (highly recommended). However, the to_yaml method is not documented in the discussion of the Object class - it's not reasonable to expect EVERYTHING to be covered, I'm sure.

25

Tom Cloyd wrote:

James Gray wrote:

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

And then what's left shows correctly under std-lib.

Though, ideally, there would be no distinction, and looking at the docs for any method or class, etc would simply tell you what, if anything, need be require'd.

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?

I believe it docs everything it finds.

(Side question: why are those .document files the way they are, if the results aren't what they should be?)

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

I sort of am the owner. I need to spend more time with it so as to be a proper owner.

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

Thank you very much.

Short term goal: a low-maintenance approach (e.g., it cannot break when cron does an svn up to get the newest source) to passing rdoc over the source such that ruby-doc.org/core/* shows just the core, and ruby-doc.org/std-lib/*. Cron'ed tasks that, after re-upping from svn, munge .document files, is a likely target.

Long-term: a way for everyone to run rdoc or its successor over the complete source tree and get a single set of docs that clearly indicate when something is core or not, and how to make things Just Work.

An ideal (to me, currently) end result would be a process that took atomic rdoc data and populated a database; API docs pages would then be generated from that database, allowing for interesting (and, I hope, useful) queries.

It would nice, for example, to easily see what libs, bundled with a standard Ruby distro, will alter String if included.

Or to have a Web page showing String docs, with ajazzy hooks to show/hide the results of including various modules (such as YAML)

···

--
James Britt

"I never dispute another person's delusions, just their facts."
   - Len Bullard

26

Dave Thomas wrote:

Agreed - with all. And I own a copy of Pickaxe 2nd ed., in marvelous searchable PDF format (highly recommended). However, the to_yaml method is not documented in the discussion of the Object class - it's not reasonable to expect EVERYTHING to be covered, I'm sure.

Tom:

(page numbers below are for the printed copy)

Page 758 is the description of the YAML standard library.

Because it's a standard library, you know you need to use require (page 653). And the examples on the YAML page all show the use of require.

I hadn't realized you owned a copy of the book--if I had, I could have saved you time by pointing you at these pages.

Just to reiterate: to_yaml is not a method of the built-in Object class. That's why it doesn't appear in the documentation of object. When you do <rewquire 'yaml'>, that library _adds_ the method to object.

Dave Thomas

OK, but consider my situation: Using the online documentation (links to which I've already given), I see two things - to_yaml IS a part of Object class, AND it appears in association with MANY other classes. This is not only not a simple picture, it is downright misleading.

When that documentation tells me that it is a method of the Object class, I naively believe it. What else am I to do? I'm a beginner, after all. I tend to trust the experts. And, I note that this is a Very Important Class. I assume that if any class has received attention in its documentation, this would be at the top of the list.

I entered this fray well aware of the YAML library, as I've already made extensive us of it in two programs I wrote for my own (rather frequent) use. THIS method looked related BUT clearly part of the Object class. If the documentation is wrong, or simply inadequate, I can understand where things went wrong. Otherwise, I remain confused, as I don't see why a method of the Object class should be "required". I'll keep thinking on it, but I'm not hopeful of making sense of this.

Doing the best I can...

t.

···

On Mar 16, 2008, at 11:37 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)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

27

Tom Cloyd wrote:

James Gray wrote:

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

And then what's left shows correctly under std-lib.

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?

I believe it docs everything it finds.

(Side question: why are those .document files the way they are, if the results aren't what they should be?)

Yeah, good point. I just checked and you're right in that it must be ignoring them.

What about blowing away lib/ and ext/? Does that work?

Long-term: a way for everyone to run rdoc or its successor over the complete source tree and get a single set of docs that clearly indicate when something is core or not, and how to make things Just Work.

An ideal (to me, currently) end result would be a process that took atomic rdoc data and populated a database; API docs pages would then be generated from that database, allowing for interesting (and, I hope, useful) queries.

It would nice, for example, to easily see what libs, bundled with a standard Ruby distro, will alter String if included.

Or to have a Web page showing String docs, with ajazzy hooks to show/hide the results of including various modules (such as YAML)

We should be sharing these great ideas with Eric Hodel, who has been revamping RDoc lately, I believe.

James Edward Gray II

···

On Mar 17, 2008, at 12:07 AM, James Britt wrote:

28

The current ruby-doc.org core documentation has been built to include things that are not core. That's easily fixed by the owners of the site, and, no that you've pointed it out, I'd assume that this is something that will happen.

So, let's move on.

Dave

···

On Mar 16, 2008, at 12:13 PM, Tom Cloyd wrote:

OK, but consider my situation: Using the online documentation (links to which I've already given), I see two things - to_yaml IS a part of Object class, AND it appears in association with MANY other classes. This is not only not a simple picture, it is downright misleading.

29

One last tip...
with many libraries, you will want to browse the library and its files themselves. Sometimes, especially in the beginning, this can be overwhelming, since some libraries have certainly been refined by multiple people over many years. But generally, digging through the source of many libraries can lead you to insights on working with Ruby itself, and sometimes is all the documentation you get ...