Add real API documentation and examples

[JamesMGreene]

Your module has proved itself to be incredibly useful to me in my work. However, your README documentation is nearly non-existent and some of what is there is incorrect (e.g. it mentions only 3 exposed functions, then subsequently shows 2 different ones being used, and doesn't mention the myriad others). 😕

[whitequark]

Sorry, I have no time to write this.

[silverwind]

👍 I too found the README quite hard to parse. A TOC and one header per method should make it easier to consume the docs.

[tchakabam]

Hi everyone,

Just wanted to let you know I wrote a bit about the usefulness of ipaddr.js on a Stackoverflow post: https://stackoverflow.com/questions/9208814/validate-ipv4-ipv6-and-hostname/64234425

Thought this would be a good place to share this. Please feel free to re-edit. I think it is also a good documentation of the library and usage example as well as explicative of how it works. Maybe the post can be used as documentation or usage example anyhow.

This library was very helpful for an actual issue in a project, and also the TypeScript bindings 👌

@JamesMGreene Why you don't contribute the missing documentation yourself, since you seem to know what you'd want there?

[JamesMGreene]

Why you don't contribute the missing documentation yourself, since you seem to know what you'd want there?

It definitely would've been a great idea 3.5 years ago, @tchakabam! Sadly, at the time, I wasn't very knowledgeable on ipaddr.js yet. Even more sadly, now, at this time, I have forgotten pretty much everything I learned about ipaddr.js back then and haven't had a need for it since. 😓