Improve README. Docs. about transitions

[qoobaa]

Feel free to write one ;-). Any other volunteers?

[jerodsanto]

Its pretty lame to agree to maintain somebody else's code and not even be willing to write any documentation whatsoever.

I think I'll just use state_machine instead.

[qoobaa]

LOL :-)

It's pretty lame to complain about other people work and not even be willing to do anything to improve it. I didn't know that I'm obliged to write a documentation after I put an effort to create the gem. You're free to fork the code and do whatever you want with it but don't tell me what I should do, ok?

[ans82]

bam... i'new to rails and statemachines. was happy to find this gem, but the doc is still a bit short. maybe you should mention that the default attribute used is "state" AND it is a string. migrated my database with "state :integer" and it took me quite a while to figure out what was going wrong. hope this helps someone!

[qoobaa]

If you're new to Rails, you should be probably using state_machine gem instead of this one. I created the gem to use it in one of my apps, but finally I used state_machine instead. I don't use the gem now, so I don't have enough time to improve it.

[netizer]

I wrote about this gem a while ago.
http://dev.netizer.pl/transitions-state-machine-for-rails-3.html
You can use my example, or add a link to my article.

[qoobaa]

Added to readme. Thanks.

[Burgestrand]

In the interest of knowing what to fix in this issue, what would a more complete readme contain? I’m a newbie to this gem myself, and here’s some questions I would’ve liked an answer to (before I read through the code):

• why two modules (Transitions & AR::Transitions)?
• what is the state variable, is it persistent (how?), can I have more than one?
• where can I find an API reference for method options (:guard, :on_transition)?
• how do I fire transitions (also explain bang vs. non-bang call)?
• state query methods?
• “maybe you should mention that the default attribute used is "state" AND it is a string”

I’ll see if I can get myself to write a coherent piece of answers to the above questions. :)

PS: Thanks for maintaining this qoobaa, took me some searching to find this repository but I’m happy I found it. I prefer the DSL of this gem to the others… it feels slinky.

(edit 3th October: added note point about “state” attribute being a string)

[qoobaa]

There's no need for including two modules (AR::Transitions includes ::Transitions). If you have some time to improve the docs we'd appreciate it :-).

[Burgestrand]

I forked, branched and slightly rewrote the README, adding information about the points I listed. Next up is some actual API documentation; I’ve already begun on the public API :)

[troessner]

@Burgestrand Would you mind submitting a pull request with your documentation updates?

[Burgestrand]

@troessner I did not get very far with the API documentation; I had a few methods documented, but I’ve since lost the repository. All work I did on my fork have already been merged by Jakob (see commit 2cd5024 and earlier).

[troessner]

@Burgestrand Alright -> closing this issue.