System.on() and System.off(); needs to be documented more completely

[technobly]

https://github.com/particle-iot/firmware/blob/develop/wiring/inc/spark_wiring_system.h#L219-L241

    static bool on(system_event_t events, void(*handler)(system_event_t, int,void*)) {
        return !system_subscribe_event(events, reinterpret_cast<system_event_handler_t*>(handler), nullptr);
    }

    static bool on(system_event_t events, void(*handler)(system_event_t, int)) {
        return system_subscribe_event(events, reinterpret_cast<system_event_handler_t*>(handler), NULL);
    }

    static bool on(system_event_t events, void(*handler)(system_event_t)) {
        return system_subscribe_event(events, reinterpret_cast<system_event_handler_t*>(handler), NULL);
    }

    static bool on(system_event_t events, void(*handler)()) {
        return system_subscribe_event(events, reinterpret_cast<system_event_handler_t*>(handler), NULL);
    }

    static void off(void(*handler)(system_event_t, int,void*)) {
        system_unsubscribe_event(all_events, handler, nullptr);
    }

    static void off(system_event_t events, void(*handler)(system_event_t, int,void*)) {
        system_unsubscribe_event(events, handler, nullptr);
    }

You can logically OR system events together with System.on(event1 | event2 | event3, handler);

To unregister a system handler, you can call System.off(handler) when you have previously called System.on(event1 | event2 | event3, handler); to unregister all events, or System.off(event3, handler); to unregister just event3

Note: event1,2,3 just temp names, refer to system events in docs for all available events.

[JesusFreke]

Also, It would be nice if there were overrides of System.off that accepted the other handler signatures that System.on accepts.

[ScruffR]

This might be pedantic but since the semantic meaning of on in System.on() (or "on occasion of") is not compatible with the semantic meaning of on as opposite of off the naming may seem confusing - if not abusing the language. You can say "on occasion of" but "off occasion of" isn't the opposite 😎

When you hear System.off() it rather suggests to turn the System off where System.on() would do the same thing as powering the device - start it running.

An alternative might be System.ignore(event) and/or the introduction of an operator+= for System.on() (as known from e.g. C#) and its opposite operator-=.

[JesusFreke]

System.DontSendMeTheEventAnymore()