api_spec.md has a lot of content, but doesn't always describe the intended usage of certain components.
For example, state["current_subtask"] should really only be used by a few internal functions, everything else should use get_current_subtask_key() (or get_current_subtask()).
Similarly, annotations shouldn't be marked "deprecated" directly, they should use mark_deprecated() (see #194).
Some of this "common usage" or "best practices" should be documented in a single spot, to avoid confusion and prevent future bugs.
api_spec.mdhas a lot of content, but doesn't always describe the intended usage of certain components.For example,
state["current_subtask"]should really only be used by a few internal functions, everything else should useget_current_subtask_key()(orget_current_subtask()).Similarly, annotations shouldn't be marked "deprecated" directly, they should use
mark_deprecated()(see #194).Some of this "common usage" or "best practices" should be documented in a single spot, to avoid confusion and prevent future bugs.