Argh! more undocumented mysteries: to_yaml

Ruby
21

Dave T. wrote:

(page numbers below are for the printed copy)
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 T.

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.

–

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

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 …

23

On Mar 16, 2008, at 12:13 PM, Tom C. 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.

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

24

Dave T. wrote:

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

Regards

Dave T.

–
James B.

“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

25

James G. wrote:

can be misleading.

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

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

James Edward G. 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.

–

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

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

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 K. manages (or at least did), right?

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

James Edward G. II

27

Tom C. wrote:

James G. 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 K. 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 B.

“I never dispute another person’s delusions, just their facts.”

  • Len Bullard
28

On 2008-03-16, Tom C. [email protected] wrote:

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.

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

Jeremy H.

29

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

Tom C. wrote:

James G. 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?

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 H., who has been
revamping RDoc lately, I believe.

James Edward G. II