oxidecomputer/steno

Unclear documentation of "saga_create/saga_start" in SecClient

Closed this issue · 0 comments

SecClient::saga_create is documented with:

steno/src/sec.rs

Lines 128 to 131 in 8da3eda

* Create a new saga and start it running
*
* This function asynchronously returns a `Future` that can be used to wait
* for the saga to finish. It's also safe to cancel (drop) this Future.

As stated, the documentation implies that invoking saga_create will start running the saga.

However, SecClient::saga_start is documented as:

steno/src/sec.rs

Lines 211 to 212 in 8da3eda

* Start running (or resume running) a saga that was created with
* [`SecClient::saga_create()`] or [`SecClient::saga_resume()`].

This documentation implies that a saga_create-ed saga won't run until saga_start is invoked.

This documentation is somewhat contradictory - judging by the examples, invoking "create" and then "start" is necessary to actually execute the saga?