argh! more undocumented mysteries: to_yaml
Tom Cloyd
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
<< t...@tomcloyd.com >> (email)
<< TomCloyd.com >> (website & psychotherapy weblog)
<< sleightmind.wordpress.com >> (mental health issues weblog)
<< directpathdesign.com >> (web site design & consultation)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Mateusz Tybura
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 <tomc...@comcast.net>:
Stefano Crocco
> 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
Phillip Gawlowski
> 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.
>
NoMethodError: undefined method `to_yaml' for [2, 3, 4]:Array
from (irb):5
from :0
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
Tom Cloyd
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> is the parent
class <http://www.ruby-doc.org/core/classes/Object.html#M000348> of all
classes in Ruby. Its methods
<http://www.ruby-doc.org/core/classes/Object.html#M000359> 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.
Phillip Gawlowski
> 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> is the parent
> class <http://www.ruby-doc.org/core/classes/Object.html#M000348> of all
> classes in Ruby. Its methods
> <http://www.ruby-doc.org/core/classes/Object.html#M000359> 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
Tim Hunter
> 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 http://www.ruby-lang.org/en/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_
(http://www.ruby-doc.org/docs/ProgrammingRuby/) 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
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?
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
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.
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
Tom Cloyd
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.
Stefano Crocco
> 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 http://www.ruby-lang.org/en/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 http://www.ruby-lang.org/en/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
Tom Cloyd
make a note to try requiring something if it doesn't seem to be
available. I fault myself for not thinking of that!
Tom Cloyd
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.
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.
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. ;)
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
Tom Cloyd
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 http://www.ruby-doc.org/core/
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.
Tom Cloyd
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.
James Britt
>
> 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
Tim Hunter
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.)
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.
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
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.
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
Tom Cloyd
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...
Dave Thomas
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.
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
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
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? "
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...
James Britt
> 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
Jeremy Henty
> 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 :).
>
> 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.
/me applauds Tom Cloyd's graciousness. Seriously, it's good to see
someone with a genuine complaint being so positive.
Jeremy Henty
James Gray
> 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