Re: SLB vs LuaBind

[Tim Mensch <tim-lua-l@...>]

On 1/8/2011 1:50 AM, beo wulf wrote:
> Something may have been misunderstood here. My comment was in
> reference to documentation, not unit-testing. I.e., there's a general
> concern that SLB lacks documentation -- and in my experience, that's
> not a big deal -- a few sample code snippets here & there is more than
> enough to figure out what's going on.

You're in agreement with Liam, but not me, here.

Documentation doesn't need to (and ideally shouldn't) take the place of
examples or unit tests, but having a few words to describe the intent of
each API and not have to derive that from sample code is priceless, IMO,
if only because the ORGANIZATION of documentation is better for humans
than the organization a bunch of tests would take.

Documentation only gets to be out of date if you let it. It's not THAT
hard to take a second to tweak the docs when an interface changes -- I
mean, ideally you're not breaking interfaces with each change, right? I
managed to write and maintain 500+ pages of documentation on a library
while developing it (in addition to posting 3000 support messages to the
forums), with only the occasional bit ending up outdated -- and updating
that when someone noticed typically took no more than a few seconds. If
you use Doxygen/Javadocs/Luadocs, then the documentation is sitting
right next to the code you're changing, and you don't even need to
change files in your editor to update it. Doxygen even documents the
actual parameters of a function, regardless of whether you've added
documentation for them. If you have some wiki or other site with
documentation hidden far from the code it documents, then sure, it can
be a pain to update it. My answer is: Don't do it that way.

That said, we're talking about volunteer time being put toward projects
that are available for free. Do what you feel like on them; don't let me
or anyone else tell you what you "should" be doing, or the project could
end up being less fun and die from neglect as you lose interest.

But when you ask what is preventing a user from adopting your library,
and they say it's documentation or something else you don't feel like
adding, please don't whine about how what they want is "not important."
Documentation will remain important to me no matter how much you
rationalize your position.

Tim