Hi John
=> improvements - new user documentation <=
I would add to the documentation a small section on trouble shooting the compile. When I started out, the fact that state machine connectivity was specified in templates caused me a bit of head scratching. My typical new-user mistakes resulted in lots of error messages. I would explicitly address this area, describing how connectivity errors cause compile time errors, for common state machine hook up errors. For example, if I change the "context" for just one state from the correct value to an incorrect value, I get over 90 lines of output.
Hmmm, I'm wondering which version of the library you are/were using? A few months ago, I've added additional compile-time checks. While these do not reduce the length of the error messages, they should surely help you pinpoint the problem. In the library code, at the point of the error, there should always be a comment that describes the root cause of the problem. From there, you can follow the compilers backtrace until you reach a point in your code. Almost always, this first point in your code is also the point where the error is. You surely figured out the above yourself, I just wanted to ask you what version you used in the beginning and whether you have any examples of errors where there is no such comment in the library code. [snip]
I think if you explicitly described a simple strategy for tracking down these connectivity problems, it would help the new user.
Noted, I will do that. [snip]
- In addition, I have provided an IFsmState<> template that implements a "GetState()" function that can be called by the state machine.
I guess this machinery predates the introduction of state iteration (see state_machine::state_begin())? More on this below.
{
class SystemFsm : public IFsmStateQuerry, public fsm::state_machine< SystemFsm, StNoHazard public: SystemFsm() { } // ...
// Get state information. const type_info & GetState() const { // state_cast produces object in active state. // GetState returns type_info for that state. return state_cast< const IFsmStateQuerry & >().GetState(); } };
With the current version of the library this could be implemented as follows (requires the definition of BOOST_FSM_USE_NATIVE_RTTI in all translation units) ... // untested code class SystemFsm : public fsm::state_machine< SystemFsm, StNoHazard > { public: const type_info & GetState() const { if ( terminated() ) { throw std::bad_cast("Machine terminated"); } return typeid( *state_begin() ); } }; ... and makes IFsmState<> obsolete. [snip]
- I also think the central role of the "context" parameter in simple_state<>, when specifying how to connect up all the states, could be stressed more, esp. for new users.
Ok, noted. Thanks for your review! Best Regards, Andreas -- Andreas Huber When replying by private email, please remove the words spam and trap from the address shown in the header.