Okay, I will admit that I was trolling a bit when I wrote that original
post. I apologize – it was the end of a frustrating day. Sorry for
injecting negativity on the forums.
That having been said, my source of frustration was that yes, okay -
there is a new version of the gem out. I ran my scripts, things broke
and I started looking through my code to find the problem. The error
message I got when calling “save” was that I was passing a boolean where
a hash was expected.
So, sure enough, I dig through my trusty RDocs to find the documentation
for the newest version of the gem. Here is where things went wrong for
me and I posted in the forums – the API doc for save, at least when I
looked, had not been updated to reflect the new signature for the “save”
method. So…at least in my view of programming, if you do something as
significant as changing the signature of a method as VITAL as “save”,
you had better update that in the API doc.
It’s good that there’s a libxml-ruby forum - and I did check it for
threads but nothing jumped out - but I don’t find it reasonable to
expect folks to have to go to the forum for updates on such a
significant refactoring. If you change something as important as “save”,
that MUST be updated in the RDoc. No ifs, ands, or buts about it.
Should I go dig through the source code if I think the RDoc is wrong?
Well…on the one hand, I’m sort of forced to do that, but I don’t think
that should be required. Just because we’re using open source software
doesn’t mean that people should get sloppy. If you bothered to write the
doc once, you’ve created an expectation that it’s going to stay updated.
Did this turn into another rant? I suppose, but I just wanted to get it
out there.
Again – I just want to emphasize that libxml-ruby has been a great tool
in my toolbelt for the past few months. It’s blazingly fast, gets stuff
done fast, and I’ve generally found it to be pretty easy to work with
(as easy as XML lends itself to be, but we’ll let that go by). So…I
guess the frustration also came from me being used to the library being
so great. When something that has been tried and true suddenly blows up,
I get a little miffed. Whether or not that’s justified is something we
can debate, I guess. : )