Action documentation rewrite and initializer renaming.

[andersio]

The documentation rewrite in this PR attempts to explain the mechanics around the concept of:

1. Action representing a repeatable work; and
2. the apply() producer attempting to create and start a unit of work.

Consequently, Action(input:_:) has been renamed to Action(state:_:), since input refers to the varying input associated with execution attempts.

[mdiep]

Typo of repeatable here

[mdiep]

I don't think these names are an improvement over the current names.

1. state seems less accurate than input. I wouldn't say that this property describes the state of the Action. It's the inputs that are used—consumed in a reactive way.

2. workProducer is a bit misleading because it's not a producer itself—it's a closure that returns a producer. So I think execute is a preferable name here as well.

[andersio]

I wouldn't say that this property describes the state of the Action. It's the inputs that are used—consumed in a reactive way.

The point is though the term input is already bound to the external input from the caller-facing apply() since it is also part of the type name. So calling this input leads to two interpretations of the same term, which do not seem nice for documentation purpose.

After all, this work all derived from a question of "why is it the input when Input is Void".

Moreover, it is just a more specific version of init(state:enabledIf:_:), and the semantic hasn't really changed. If this shouldn't be called state, why should the most generic version be in terms of consistency?

If state is not the right choice, how about external input vs internal input?

workProducer is a bit misleading because it's not a producer itself—it's a closure that returns a producer. So I think execute is a preferable name here as well.

I can't defend workProducer in this regard. But execute doesn't seem right either, since it doesn't really execute but returns something to be executed. workFactory, producerFactory or workCustomizer are possible alternatives.

[mdiep]

I'm 👍 with state.

I can't defend workProducer in this regard. But execute doesn't seem right either, since it doesn't really execute but returns something to be executed. workFactory, producerFactory or workCustomizer are possible alternatives.

True, but I think most things that return SignalProducers are named this way. Look at the methods in Carthage or any of its dependencies, for example.