I've been reading through the various questions asking whether or not API reviews are on topic, but they've left me a bit confused.
In particular "Are questions about public interface (API) on topic?" seems to suggest that API review questions are on topic as long as the code is included. However, sometimes a small API can have a large amount of backing code that wouldn't be suitable for this site. Or the code may not be written yet, but that doesn't mean there aren't objective points that could be made about the API to save someone time or help make their job easier later when they go to actually implement it.
To be clear, I'm not looking for a comparative "is this API better than this other API" or help designing an API, I'm specifically wondering if questions about a specific API design (listed in the question) are on topic. For example, if I posted something like the following Go-esq API (an early version of the actual API I'd like to ask about if it's deemed on topic):
// Mechanism represents an RFC 4422 SASL mechanism (eg. SCRAM-SHA-1 or PLAIN)
type Mechanism struct {
Names []string
Start func() (more bool, resp []byte, err error)
Next func(state State, challenge []byte) (more bool, resp []byte, err error)
// contains filtered or unexported fields
}
// Err returns the last error generated by the mechanism.
func (c *Mechanism) Err() error
// Reset resets the mechanisms internal state machine so you can use it for another auth attempt.
func (c *Client) Reset()
// State returns the mechanisms internal state (see the State constants for more info)
func (c *Client) State() State
// Given a challenge from the server, Step attempts to advance the mechanism to its next state. It enforces directionality in the state machine and does not allow it to go backwards (unless reset resets it to the beginning).
func (c *Client) Step(challenge []byte) (more bool, resp []byte, err error)
// State is a represents the internal state of a Mechanism.
type State int8
const (
Initial State = iota
AuthTextSent
ResponseSent
ValidServerResponse
)
When asked for a review, someone might point out that if my mechanisms are stateful then you'll have to know your username and password when you decide what mechanisms are supported if you want to create a list of mechanisms as opposed to deferring needing to know them until the actual negotiation takes place. Or you'll have to have a list of mechanisms as sentinel values and map these to actual Mechanism constructors later, or they might point out that someone could construct a mechanism with a Start or Next function that was stateful itself, thereby breaking Reset's ability to effectively reset the state of the Mechanism. These are objective problems with the above API, but I never actually posted a line of code.
Would API review with a full, documented, API but no implementation like this be on topic?
