argh! more undocumented mysteries: to_yaml

[Tom Cloyd]

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.

--

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

 

[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.

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

 

[John Joyce]

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

 

[James Britt]

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

 

[James Gray]

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

 

[Tom Cloyd]

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.

--

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

 

[James Britt]

James Gray wrote:

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

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

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 Gray]

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


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