Mtasa-blue: Pin down startResource and stopResource behaviour

[qaisjp]

The latest release has this behaviour:

• stopResource returns false and warns if the resource is already stopped
• startResource returns true if the resource is already stopped

In master (via 2527293138927224979f40ba77bd6251964bf514) this behaviour is changed. (This change in API is not obvious from or mentioned in the commit message.)

A default MTA resource relies on undocumented behaviour that never worked (it expects stopResource to return true if already stopped).

We need to discuss and pin down this part of the Lua API.

[botder]

If the resource is in the desired state, should the called function return false, because there was nothing to do, or should the called function return true, because the 'operation' was successful? I prefer the latter.

[qaisjp]

I believe it should return false.

there was nothing to do, or [..] the 'operation' was successful

I think this would be a more accurate way of describing the lifecycle of a resource:

All of these, with the exception of deleted?, is a state returned by getResourceState. Since it's not possible to _request_ a transition _from_ starting, stopping or failed to load, any requests on those states should return false.

Of course, this diagram has been created based on how _I_ expect the resource lifecycle to function. I could be wrong or you might see it in a different way. (If you want to fork the diagram, you can use this html file with draw.io.)

As an aside, I believe getResourceLoadFailureReason has a contradictory description. The function says "load failure reason", but the description says it "retrieves the reason why a resource failed to start". This should be cleared up with a notebox (if it truly includes the start failure reason) or a simple amendment (if this is just shoddy wording).

[obuhhh]

Is it really more important than pool performance or custom weapons/peds synchronization?

[miusman]

Oh no. Better to return false. This is a common behavior. Examples:
deleteResource returns false if resource doesnt exist
removeCommandHandler returns false if command doesnt exist
removePedFromVehicle returns false if ped is not in vehicle

[botder]

I changed my mind. startResource and stopResource should return false if the resource is already running or stopped, respectively.

[qaisjp]

Seems like the verdict is to return false if already in the target state. Pull requests to implement this would be appreciated.