More Documentation

[bryceschober]

Is there any documentation beyond that in the README.md?

1. It's not clear to me what is the intended API surface area for a non-advanced state machine usage.
2. It's not clear to me what exactly is intended with the substitute() method.
3. You kinda introduce the concept of a timed state in your April 2017 presentation and in the test/main.cpp without any built-in support or introductory documentation how to extend states properly. This would be helped by a more-fully worked player character example via issue More Complete Examples #11, of course... but I wonder if perhaps some of those extensions are worth providing in the library.

[andrew-gresyk]

OK, I'll add more detailed tutorial, together with examples it should help.
Substitute, injections aren't covered in readme, they deserve dedicated pages.

[andrew-gresyk]

FYI, I'm reworking the docs, if you want to check the new README and tutorial.
substitute() page is coming soon.

[bryceschober]

FYI, the link to the example in the tutorial is currently broken.

[bryceschober]

Some feedback on the design this time, after reading through the tutorial and example and actually mostly understanding it this time:

I found myself wishing that the state types were more explicit as I read through their definitions. It seems that most states would be designed to always fit into the same kind of slot in the hierarchy, and it would be helpful if their declarations were more explicit.

If a state is destined to be the head or a non-head sub-state, then it would be helpful to declare it as such, and it would enable compile-time checking of the eventual state machine construction. Same goes for differentiation between region types: if a state is destined for a composite vs. an orthogonal region, then it would be helpful to declare it as such and check the construction at compile time.

Even if the implementation of the state is identical, they could still be "strong types" that are "tagged" for more readably and verifiably different uses.

[andrew-gresyk]

I see. How would you suggest to implement this?

[andrew-gresyk]

All existing docs were moved to Wiki, more is coming, see sidebar for the planned list of topics.