Commenting session request structs

requests.go

@@ -93,12 +93,16 @@ type ServerJwt struct {
 	IssuedAt   Timestamp `json:"iat"`
 }
 
+// RequestorBaseRequest contains fields present in all RequestorRequest types
+// with which the requestor configures an IRMA session.
 type RequestorBaseRequest struct {
 	ResultJwtValidity int    `json:"validity"`    // Validity of session result JWT in seconds
 	ClientTimeout     int    `json:"timeout"`     // Wait this many seconds for the IRMA app to connect before the session times out
 	CallbackUrl       string `json:"callbackUrl"` // URL to post session result to
 }
 
+// RequestorRequest is the message with which requestors start an IRMA session. It contains a
+// SessionRequest instance for the irmaclient along with extra fields in a RequestorBaseRequest.
 type RequestorRequest interface {
 	Validator
 	SessionRequest() SessionRequest
@@ -186,7 +190,7 @@ func (r *IdentityProviderRequest) Base() RequestorBaseRequest {
 	return r.RequestorBaseRequest
 }
 
-// SessionRequest is an IRMA session.
+// SessionRequest instances contain all information the irmaclient needs to perform an IRMA session.
 type SessionRequest interface {
 	Validator
 	GetNonce() *big.Int

server/api.go

@@ -167,6 +167,10 @@ func WriteString(w http.ResponseWriter, str string) {
 	w.Write([]byte(str))
 }
 
+// ParseSessionRequest attempts to parse the input as an irma.RequestorRequest instance, accepting (skipping "irma.")
+//  - RequestorRequest instances directly (ServiceProviderRequest, SignatureRequestorRequest, IdentityProviderRequest)
+//  - SessionRequest instances (DisclosureRequest, SignatureRequest, IssuanceRequest)
+//  - JSON representations ([]byte or string) of any of the above.
 func ParseSessionRequest(request interface{}) (irma.RequestorRequest, error) {
 	switch r := request.(type) {
 	case irma.RequestorRequest:
@@ -214,7 +218,9 @@ func tryUnmarshalJson(bts []byte, attempts []irma.Validator) (irma.Validator, er
 	return nil, errors.New("")
 }
 
+// LocalIP returns the IP address of one of the (non-loopback) network interfaces
 func LocalIP() (string, error) {
+	// Based on https://play.golang.org/p/BDt3qEQ_2H from https://stackoverflow.com/a/23558495
 	ifaces, err := net.Interfaces()
 	if err != nil {
 		return "", err

server/irmaserver/main.go

@@ -48,6 +48,8 @@ func New(conf *server.Configuration) (*Server, error) {
 // StartSession starts an IRMA session, running the handler on completion, if specified.
 // The session token (the second return parameter) can be used in GetSessionResult()
 // and CancelSession().
+// The request parameter can be an irma.RequestorRequest, or an irma.SessionRequest, or a
+// ([]byte or string) JSON representation of one of those (for more details, see server.ParseSessionRequest().)
 func StartSession(request interface{}, handler SessionHandler) (*irma.Qr, string, error) {
 	return s.StartSession(request, handler)
 }