[grpc] Add documentation

dfssc/api/client.pb.go

@@ -35,14 +35,24 @@ var _ = math.Inf
 // is compatible with the proto package it is being compiled against.
 const _ = proto.ProtoPackageIsVersion1
 
+// / Context stores the current context of a specific promise or signature.
+// It is a kind of "symbolic" promise, with no real cryptographic proofs inside.
 type Context struct {
-	RecipientKeyHash     []byte   `protobuf:"bytes,1,opt,name=recipientKeyHash,proto3" json:"recipientKeyHash,omitempty"`
-	SenderKeyHash        []byte   `protobuf:"bytes,2,opt,name=senderKeyHash,proto3" json:"senderKeyHash,omitempty"`
-	Sequence             []uint32 `protobuf:"varint,3,rep,name=sequence" json:"sequence,omitempty"`
-	Signers              [][]byte `protobuf:"bytes,4,rep,name=signers,proto3" json:"signers,omitempty"`
-	ContractDocumentHash []byte   `protobuf:"bytes,5,opt,name=contractDocumentHash,proto3" json:"contractDocumentHash,omitempty"`
-	SignatureUUID        string   `protobuf:"bytes,6,opt,name=signatureUUID" json:"signatureUUID,omitempty"`
-	SignedHash           []byte   `protobuf:"bytes,7,opt,name=signedHash,proto3" json:"signedHash,omitempty"`
+	// / SHA-512 certificate hash
+	RecipientKeyHash []byte `protobuf:"bytes,1,opt,name=recipientKeyHash,proto3" json:"recipientKeyHash,omitempty"`
+	// / SHA-512 certificate hash
+	SenderKeyHash []byte `protobuf:"bytes,2,opt,name=senderKeyHash,proto3" json:"senderKeyHash,omitempty"`
+	// / The signing sequence used
+	Sequence []uint32 `protobuf:"varint,3,rep,name=sequence" json:"sequence,omitempty"`
+	// / The list of signers hashes, as provided by the dfss file.
+	// The order is very important.
+	Signers [][]byte `protobuf:"bytes,4,rep,name=signers,proto3" json:"signers,omitempty"`
+	// / The contract document hash, as provided by the dfss file
+	ContractDocumentHash []byte `protobuf:"bytes,5,opt,name=contractDocumentHash,proto3" json:"contractDocumentHash,omitempty"`
+	// / The unique signature attemp ID, as provided by the platform during the ready signal
+	SignatureUUID string `protobuf:"bytes,6,opt,name=signatureUUID" json:"signatureUUID,omitempty"`
+	// / The signed metadata hashb, as provided by the platform during the ready signal
+	SignedHash []byte `protobuf:"bytes,7,opt,name=signedHash,proto3" json:"signedHash,omitempty"`
 }
 
 func (m *Context) Reset()                    { *m = Context{} }
@@ -50,12 +60,13 @@ func (m *Context) String() string            { return proto.CompactTextString(m)
 func (*Context) ProtoMessage()               {}
 func (*Context) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{0} }
 
-// Promise message contains all the required information to verify
-// the identity of the sender and receiver, and the actual promise
 type Promise struct {
+	// / Metadata
 	Context *Context `protobuf:"bytes,1,opt,name=context" json:"context,omitempty"`
-	Index   uint32   `protobuf:"varint,2,opt,name=index" json:"index,omitempty"`
-	Payload []byte   `protobuf:"bytes,3,opt,name=payload,proto3" json:"payload,omitempty"`
+	// / The index of the sequence for this promise
+	Index uint32 `protobuf:"varint,2,opt,name=index" json:"index,omitempty"`
+	// / The crypographic payload, currently NOT IMPLEMENTED
+	Payload []byte `protobuf:"bytes,3,opt,name=payload,proto3" json:"payload,omitempty"`
 }
 
 func (m *Promise) Reset()                    { *m = Promise{} }
@@ -70,11 +81,11 @@ func (m *Promise) GetContext() *Context {
 	return nil
 }
 
-// Signature message contains all the required information to verify
-// the identity of the sender and receiver, and the actual signature
 type Signature struct {
+	// / Metadata
 	Context *Context `protobuf:"bytes,1,opt,name=context" json:"context,omitempty"`
-	Payload []byte   `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"`
+	// / The crypographic payload, currently NOT IMPLEMENTED
+	Payload []byte `protobuf:"bytes,2,opt,name=payload,proto3" json:"payload,omitempty"`
 }
 
 func (m *Signature) Reset()                    { *m = Signature{} }
@@ -89,9 +100,9 @@ func (m *Signature) GetContext() *Context {
 	return nil
 }
 
-// Hello message is used when discovering peers.
-// It contains the current version of the software.
+// / Hello message is used when discovering peers.
 type Hello struct {
+	// / Used version of DFSS client
 	Version string `protobuf:"bytes,1,opt,name=version" json:"version,omitempty"`
 }
 
@@ -118,8 +129,11 @@ const _ = grpc.SupportPackageIsVersion2
 // Client API for Client service
 
 type ClientClient interface {
+	// / Handle reception of promises.
 	TreatPromise(ctx context.Context, in *Promise, opts ...grpc.CallOption) (*api1.ErrorCode, error)
+	// / Handle receptions of signatures.
 	TreatSignature(ctx context.Context, in *Signature, opts ...grpc.CallOption) (*api1.ErrorCode, error)
+	// / Permits initial handshake for P2P between clients.
 	Discover(ctx context.Context, in *Hello, opts ...grpc.CallOption) (*Hello, error)
 }
 
@@ -161,8 +175,11 @@ func (c *clientClient) Discover(ctx context.Context, in *Hello, opts ...grpc.Cal
 // Server API for Client service
 
 type ClientServer interface {
+	// / Handle reception of promises.
 	TreatPromise(context.Context, *Promise) (*api1.ErrorCode, error)
+	// / Handle receptions of signatures.
 	TreatSignature(context.Context, *Signature) (*api1.ErrorCode, error)
+	// / Permits initial handshake for P2P between clients.
 	Discover(context.Context, *Hello) (*Hello, error)
 }
 

dfssc/api/client.proto

+/// Protobuf definitions for dfssc
 syntax = "proto3";
 
 package api;
-
 import "dfss/dfssp/api/platform.proto";
 
+/// Procedures offered by dfssc
 service Client {
+	/// Handle reception of promises.
 	rpc TreatPromise(Promise) returns (ErrorCode) {}
+	/// Handle receptions of signatures.
 	rpc TreatSignature(Signature) returns (ErrorCode) {}
+	/// Permits initial handshake for P2P between clients.
 	rpc Discover(Hello) returns (Hello) {}
 }
 
+/// Context stores the current context of a specific promise or signature.
+// It is a kind of "symbolic" promise, with no real cryptographic proofs inside.
 message Context {
-	bytes recipientKeyHash = 1;	// SHA-512
-	bytes senderKeyHash = 2;	  // SHA-512
-	repeated uint32 sequence = 3; // Signing sequence
-	repeated bytes signers = 4; // List of the signers' hashes
+	/// SHA-512 certificate hash
+	bytes recipientKeyHash = 1;
+	/// SHA-512 certificate hash
+	bytes senderKeyHash = 2;
+	/// The signing sequence used
+	repeated uint32 sequence = 3;
+	/// The list of signers hashes, as provided by the dfss file.
+	// The order is very important.
+	repeated bytes signers = 4;
+	/// The contract document hash, as provided by the dfss file
 	bytes contractDocumentHash = 5;
+	/// The unique signature attemp ID, as provided by the platform during the ready signal
 	string signatureUUID = 6;
-	bytes signedHash = 7; // (sequence + signers' hashes + contractDocumentHash + signatureUUID) crypted by the platform
+	/// The signed metadata hashb, as provided by the platform during the ready signal
+	bytes signedHash = 7;
 }
 
-// Promise message contains all the required information to verify
-// the identity of the sender and receiver, and the actual promise
 message Promise {
+	/// Metadata
 	Context context = 1;
-	uint32 index = 2; // The index of the sequence for this message
+	/// The index of the sequence for this promise
+	uint32 index = 2;
+	/// The crypographic payload, currently NOT IMPLEMENTED
 	bytes payload = 3;
 }
 
-// Signature message contains all the required information to verify
-// the identity of the sender and receiver, and the actual signature
 message Signature {
+	/// Metadata
 	Context context = 1;
+	/// The crypographic payload, currently NOT IMPLEMENTED
 	bytes payload = 2;
 }
 
-// Hello message is used when discovering peers.
-// It contains the current version of the software.
+/// Hello message is used when discovering peers.
 message Hello {
+	/// Used version of DFSS client
 	string version = 1;
 }

dfssd/api/demonstrator.pb.go

@@ -32,11 +32,14 @@ var _ = math.Inf
 // is compatible with the proto package it is being compiled against.
 const _ = proto.ProtoPackageIsVersion1
 
-// Log message to display information
 type Log struct {
-	Timestamp  int64  `protobuf:"varint,1,opt,name=timestamp" json:"timestamp,omitempty"`
+	// / Unix nano timestamp as absolute time of event
+	Timestamp int64 `protobuf:"varint,1,opt,name=timestamp" json:"timestamp,omitempty"`
+	// / Identifier of the sender.
+	// Should be an email, "platform" or "ttp".
 	Identifier string `protobuf:"bytes,2,opt,name=identifier" json:"identifier,omitempty"`
-	Log        string `protobuf:"bytes,3,opt,name=log" json:"log,omitempty"`
+	// / The log message
+	Log string `protobuf:"bytes,3,opt,name=log" json:"log,omitempty"`
 }
 
 func (m *Log) Reset()                    { *m = Log{} }
@@ -44,7 +47,7 @@ func (m *Log) String() string            { return proto.CompactTextString(m) }
 func (*Log) ProtoMessage()               {}
 func (*Log) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{0} }
 
-// Empty ack message
+// / Acknowledgement message
 type Ack struct {
 }
 
@@ -69,10 +72,7 @@ const _ = grpc.SupportPackageIsVersion2
 // Client API for Demonstrator service
 
 type DemonstratorClient interface {
-	// Log message.
-	//
-	// Send the UnixNano timetamp, sender's identifier and log message
-	// Returns nothing ?
+	// / Send a new log line to the demonstrator
 	SendLog(ctx context.Context, in *Log, opts ...grpc.CallOption) (*Ack, error)
 }
 
@@ -96,10 +96,7 @@ func (c *demonstratorClient) SendLog(ctx context.Context, in *Log, opts ...grpc.
 // Server API for Demonstrator service
 
 type DemonstratorServer interface {
-	// Log message.
-	//
-	// Send the UnixNano timetamp, sender's identifier and log message
-	// Returns nothing ?
+	// / Send a new log line to the demonstrator
 	SendLog(context.Context, *Log) (*Ack, error)
 }
 

dfssd/api/demonstrator.proto

+/// Protobuf definitions for dfssd
 syntax = "proto3";
 
 package api;
 
+/// Procedures offered by dfssd
 service Demonstrator {
-    // Log message.
-    //
-    // Send the UnixNano timetamp, sender's identifier and log message
-    // Returns nothing ?
-    rpc SendLog(Log) returns (Ack) {}
+	/// Send a new log line to the demonstrator
+	rpc SendLog(Log) returns (Ack) {}
 }
 
-// Log message to display information
 message Log {
-    int64 timestamp = 1;
-    string identifier = 2;
-    string log = 3;
+	/// Unix nano timestamp as absolute time of event
+	int64 timestamp = 1;
+	/// Identifier of the sender.
+	// Should be an email, "platform" or "ttp".
+	string identifier = 2;
+	/// The log message
+	string log = 3;
 }
 
-// Empty ack message
+/// Acknowledgement message
 message Ack {
 }

dfssp/api/platform.pb.go

@@ -46,17 +46,17 @@ const _ = proto.ProtoPackageIsVersion1
 type ErrorCode_Code int32
 
 const (
-	// SUCCESS is the error code for a successful request
+	// / the error code for a successful request
 	ErrorCode_SUCCESS ErrorCode_Code = 0
-	// INVARG is the error code for an invalid argument
+	// / the error code for an invalid argument
 	ErrorCode_INVARG ErrorCode_Code = 1
-	// BADAUTH is the error code for a bad authentication
+	// / the error code for a bad authentication
 	ErrorCode_BADAUTH ErrorCode_Code = 2
-	// WARNING is the error code for a success state containing a specific warning message
+	// / the error code for a success state containing a specific warning message
 	ErrorCode_WARNING ErrorCode_Code = 3
-	// INTERR is the error code for an internal server error
+	// / the error code for an internal server error
 	ErrorCode_INTERR ErrorCode_Code = -1
-	// TIMEOUT is the error code for a timeout or unreacheable target
+	// / the error code for a timeout or unreacheable target
 	ErrorCode_TIMEOUT ErrorCode_Code = -2
 )
 
@@ -82,10 +82,10 @@ func (x ErrorCode_Code) String() string {
 }
 func (ErrorCode_Code) EnumDescriptor() ([]byte, []int) { return fileDescriptor0, []int{1, 0} }
 
-// RegisterRequest message contains the client's email adress and his
-// request (ie the PEM-encoded certificate request)
 type RegisterRequest struct {
-	Email   string `protobuf:"bytes,1,opt,name=email" json:"email,omitempty"`
+	// / User mail
+	Email string `protobuf:"bytes,1,opt,name=email" json:"email,omitempty"`
+	// / Certificate request (CSR) as PEM
 	Request string `protobuf:"bytes,2,opt,name=request" json:"request,omitempty"`
 }
 
@@ -94,12 +94,15 @@ func (m *RegisterRequest) String() string            { return proto.CompactTextS
 func (*RegisterRequest) ProtoMessage()               {}
 func (*RegisterRequest) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{0} }
 
-// ErrorCode message contains an error code and a message
+// / ErrorCode message contains an error code and a message.
+//
 // Above or zero : target-side error
+//
 // Less than 0   : local error
 type ErrorCode struct {
-	Code    ErrorCode_Code `protobuf:"varint,1,opt,name=code,enum=api.ErrorCode_Code" json:"code,omitempty"`
-	Message string         `protobuf:"bytes,2,opt,name=message" json:"message,omitempty"`
+	Code ErrorCode_Code `protobuf:"varint,1,opt,name=code,enum=api.ErrorCode_Code" json:"code,omitempty"`
+	// / An additional message, if needed
+	Message string `protobuf:"bytes,2,opt,name=message" json:"message,omitempty"`
 }
 
 func (m *ErrorCode) Reset()                    { *m = ErrorCode{} }
@@ -107,10 +110,10 @@ func (m *ErrorCode) String() string            { return proto.CompactTextString(
 func (*ErrorCode) ProtoMessage()               {}
 func (*ErrorCode) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{1} }
 
-// AuthRequest message contains the client's email adress and the token used
-// for authentication
 type AuthRequest struct {
+	// / User email
 	Email string `protobuf:"bytes,1,opt,name=email" json:"email,omitempty"`
+	// / User authentication token
 	Token string `protobuf:"bytes,2,opt,name=token" json:"token,omitempty"`
 }
 
@@ -119,9 +122,8 @@ func (m *AuthRequest) String() string            { return proto.CompactTextStrin
 func (*AuthRequest) ProtoMessage()               {}
 func (*AuthRequest) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{2} }
 
-// RegisteredUser message contains the generated client certificate
-// (PEM-encoded)
 type RegisteredUser struct {
+	// / User certificate, as generated by the platform (PEM)
 	ClientCert string `protobuf:"bytes,1,opt,name=clientCert" json:"clientCert,omitempty"`
 }
 
@@ -130,7 +132,7 @@ func (m *RegisteredUser) String() string            { return proto.CompactTextSt
 func (*RegisteredUser) ProtoMessage()               {}
 func (*RegisteredUser) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{3} }
 
-// Empty message is an empty message
+// / An empty message, used when no parameters are required for a query or an answer.
 type Empty struct {
 }
 
@@ -139,13 +141,15 @@ func (m *Empty) String() string            { return proto.CompactTextString(m) }
 func (*Empty) ProtoMessage()               {}
 func (*Empty) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{4} }
 
-// PostContractRequest message contains the contract as SHA-512 hash, its filename,
-// the list of signers as an array of strings, and a comment
 type PostContractRequest struct {
-	Hash     []byte   `protobuf:"bytes,1,opt,name=hash,proto3" json:"hash,omitempty"`
-	Filename string   `protobuf:"bytes,2,opt,name=filename" json:"filename,omitempty"`
-	Signer   []string `protobuf:"bytes,3,rep,name=signer" json:"signer,omitempty"`
-	Comment  string   `protobuf:"bytes,4,opt,name=comment" json:"comment,omitempty"`
+	// / Contract SHA-512 hash
+	Hash []byte `protobuf:"bytes,1,opt,name=hash,proto3" json:"hash,omitempty"`
+	// / Contract filename
+	Filename string `protobuf:"bytes,2,opt,name=filename" json:"filename,omitempty"`
+	// / List of signers emails
+	Signer []string `protobuf:"bytes,3,rep,name=signer" json:"signer,omitempty"`
+	// / Additional comment
+	Comment string `protobuf:"bytes,4,opt,name=comment" json:"comment,omitempty"`
 }
 
 func (m *PostContractRequest) Reset()                    { *m = PostContractRequest{} }
@@ -153,8 +157,8 @@ func (m *PostContractRequest) String() string            { return proto.CompactT
 func (*PostContractRequest) ProtoMessage()               {}
 func (*PostContractRequest) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{5} }
 
-// GetContractRequest message contains the uuid of the asked contract
 type GetContractRequest struct {
+	// / UUID of the requested contract
 	Uuid string `protobuf:"bytes,1,opt,name=uuid" json:"uuid,omitempty"`
 }
 
@@ -163,11 +167,12 @@ func (m *GetContractRequest) String() string            { return proto.CompactTe
 func (*GetContractRequest) ProtoMessage()               {}
 func (*GetContractRequest) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{6} }
 
-// Contract is the return value when a contract is fetched from the platform.
-// The contract is in json format to avoid duplicating structures.
+// / The fetched contract when using GetContract
 type Contract struct {
+	// / The result code
 	ErrorCode *ErrorCode `protobuf:"bytes,1,opt,name=errorCode" json:"errorCode,omitempty"`
-	Json      []byte     `protobuf:"bytes,2,opt,name=json,proto3" json:"json,omitempty"`
+	// / The JSON object of the contract, equivalent to the one that was sent by mail to signers
+	Json []byte `protobuf:"bytes,2,opt,name=json,proto3" json:"json,omitempty"`
 }
 
 func (m *Contract) Reset()                    { *m = Contract{} }
@@ -182,11 +187,11 @@ func (m *Contract) GetErrorCode() *ErrorCode {
 	return nil
 }
 
-// JoinSignatureRequest message contains the contract to join unique identifier
-// and the port the client will be listening at
 type JoinSignatureRequest struct {
+	// / The contract UUID to join
 	ContractUuid string `protobuf:"bytes,1,opt,name=contractUuid" json:"contractUuid,omitempty"`
-	Port         uint32 `protobuf:"varint,2,opt,name=port" json:"port,omitempty"`
+	// / The open port for P2P communication of the client
+	Port uint32 `protobuf:"varint,2,opt,name=port" json:"port,omitempty"`
 }
 
 func (m *JoinSignatureRequest) Reset()                    { *m = JoinSignatureRequest{} }
@@ -194,11 +199,16 @@ func (m *JoinSignatureRequest) String() string            { return proto.Compact
 func (*JoinSignatureRequest) ProtoMessage()               {}
 func (*JoinSignatureRequest) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{8} }
 
-// UserConnected is emitted by the platform to the client to announce a new client connection
+// / UserConnected is emitted by the platform to the client to announce a new client connection, through a stream.
+// Previously connected clients are also emitted one by one just after the beginning of the stream.
 type UserConnected struct {
-	ErrorCode    *ErrorCode `protobuf:"bytes,1,opt,name=errorCode" json:"errorCode,omitempty"`
-	ContractUuid string     `protobuf:"bytes,2,opt,name=contractUuid" json:"contractUuid,omitempty"`
-	User         *User      `protobuf:"bytes,3,opt,name=user" json:"user,omitempty"`
+	// / The result code.
+	// Very bad if not equals to SUCCESS, in this case the client should close the connection
+	ErrorCode *ErrorCode `protobuf:"bytes,1,opt,name=errorCode" json:"errorCode,omitempty"`
+	// / A confirmation about the contract UUID
+	ContractUuid string `protobuf:"bytes,2,opt,name=contractUuid" json:"contractUuid,omitempty"`
+	// / One user connecting to this contract's room
+	User *User `protobuf:"bytes,3,opt,name=user" json:"user,omitempty"`
 }
 
 func (m *UserConnected) Reset()                    { *m = UserConnected{} }
@@ -221,10 +231,13 @@ func (m *UserConnected) GetUser() *User {
 }
 
 type User struct {
+	// / The certificate hash of the user
 	KeyHash []byte `protobuf:"bytes,1,opt,name=keyHash,proto3" json:"keyHash,omitempty"`
 	Email   string `protobuf:"bytes,2,opt,name=email" json:"email,omitempty"`
-	Ip      string `protobuf:"bytes,3,opt,name=ip" json:"ip,omitempty"`
-	Port    uint32 `protobuf:"varint,4,opt,name=port" json:"port,omitempty"`
+	// / The IP offered by the user for P2P
+	Ip string `protobuf:"bytes,3,opt,name=ip" json:"ip,omitempty"`
+	// / The port offered by the user for P2P
+	Port uint32 `protobuf:"varint,4,opt,name=port" json:"port,omitempty"`
 }
 
 func (m *User) Reset()                    { *m = User{} }
@@ -232,8 +245,8 @@ func (m *User) String() string            { return proto.CompactTextString(m) }
 func (*User) ProtoMessage()               {}
 func (*User) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{10} }
 
-// ReadySignRequest contains the contract unique identitier that is ready to be signed
 type ReadySignRequest struct {
+	// / The contract UUID to be ready for
 	ContractUuid string `protobuf:"bytes,1,opt,name=contractUuid" json:"contractUuid,omitempty"`
 }
 
@@ -242,13 +255,18 @@ func (m *ReadySignRequest) String() string            { return proto.CompactText
 func (*ReadySignRequest) ProtoMessage()               {}
 func (*ReadySignRequest) Descriptor() ([]byte, []int) { return fileDescriptor0, []int{11} }
 
-// LaunchSignature is emitted by the platform when every signers are ready
+// / LaunchSignature is emitted by the platform when every signers of a specific contract are ready.
 type LaunchSignature struct {
-	ErrorCode     *ErrorCode `protobuf:"bytes,1,opt,name=errorCode" json:"errorCode,omitempty"`
-	SignatureUuid string     `protobuf:"bytes,2,opt,name=signatureUuid" json:"signatureUuid,omitempty"`
-	KeyHash       [][]byte   `protobuf:"bytes,3,rep,name=keyHash,proto3" json:"keyHash,omitempty"`
-	Sequence      []uint32   `protobuf:"varint,4,rep,name=sequence" json:"sequence,omitempty"`
-	Hash          []byte     `protobuf:"bytes,5,opt,name=hash,proto3" json:"hash,omitempty"`
+	// / The result code
+	ErrorCode *ErrorCode `protobuf:"bytes,1,opt,name=errorCode" json:"errorCode,omitempty"`
+	// / The unique signature generated by the platform for this specific signature attempt
+	SignatureUuid string `protobuf:"bytes,2,opt,name=signatureUuid" json:"signatureUuid,omitempty"`
+	// / A confirmation of client hashes for communication authentication
+	KeyHash [][]byte `protobuf:"bytes,3,rep,name=keyHash,proto3" json:"keyHash,omitempty"`
+	// / The signing sequence generated on-the-fly by the platform
+	Sequence []uint32 `protobuf:"varint,4,rep,name=sequence" json:"sequence,omitempty"`
+	// / The cryptographic object of the signature of this structure (hash excepted) by the platform, for data certification.
+	Hash []byte `protobuf:"bytes,5,opt,name=hash,proto3" json:"hash,omitempty"`
 }
 
 func (m *LaunchSignature) Reset()                    { *m = LaunchSignature{} }
@@ -291,12 +309,22 @@ const _ = grpc.SupportPackageIsVersion2
 // Client API for Platform service
 
 type PlatformClient interface {
+	// / Register a new user, no authentication required.
 	Register(ctx context.Context, in *RegisterRequest, opts ...grpc.CallOption) (*ErrorCode, error)
+	// / Authenticate a previously registered user, no authentication required.
 	Auth(ctx context.Context, in *AuthRequest, opts ...grpc.CallOption) (*RegisteredUser, error)
+	// / Unregister a new user, authentication required.
 	Unregister(ctx context.Context, in *Empty, opts ...grpc.CallOption) (*ErrorCode, error)
+	// / Create a new contract, authentication required.
 	PostContract(ctx context.Context, in *PostContractRequest, opts ...grpc.CallOption) (*ErrorCode, error)
+	// / Fetch a previously create contract, authentication required.
 	GetContract(ctx context.Context, in *GetContractRequest, opts ...grpc.CallOption) (*Contract, error)
+	// / Join a signature discovery room, authentication required.
+	// The stream is triggered for each new user connected in this channel.
 	JoinSignature(ctx context.Context, in *JoinSignatureRequest, opts ...grpc.CallOption) (Platform_JoinSignatureClient, error)
+	// / Join an ignition room, authentication required.
+	// The response is returned when every signer is ready for a specific contract.
+	// Warning, can me answered with a very high delay.
 	ReadySign(ctx context.Context, in *ReadySignRequest, opts ...grpc.CallOption) (*LaunchSignature, error)
 }
 
@@ -397,12 +425,22 @@ func (c *platformClient) ReadySign(ctx context.Context, in *ReadySignRequest, op
 // Server API for Platform service
 
 type PlatformServer interface {
+	// / Register a new user, no authentication required.
 	Register(context.Context, *RegisterRequest) (*ErrorCode, error)
+	// / Authenticate a previously registered user, no authentication required.
 	Auth(context.Context, *AuthRequest) (*RegisteredUser, error)
+	// / Unregister a new user, authentication required.
 	Unregister(context.Context, *Empty) (*ErrorCode, error)
+	// / Create a new contract, authentication required.
 	PostContract(context.Context, *PostContractRequest) (*ErrorCode, error)
+	// / Fetch a previously create contract, authentication required.
 	GetContract(context.Context, *GetContractRequest) (*Contract, error)
+	// / Join a signature discovery room, authentication required.
+	// The stream is triggered for each new user connected in this channel.
 	JoinSignature(*JoinSignatureRequest, Platform_JoinSignatureServer) error
+	// / Join an ignition room, authentication required.
+	// The response is returned when every signer is ready for a specific contract.
+	// Warning, can me answered with a very high delay.
 	ReadySign(context.Context, *ReadySignRequest) (*LaunchSignature, error)
 }
 

dfssp/api/platform.proto

+/// Protobuf definitions for dfssp
 syntax = "proto3";
 
 package api;
 
+/// Procedures offered by dfssp
 service Platform {
+	/// Register a new user, no authentication required.
 	rpc Register(RegisterRequest) returns (ErrorCode) {}
+	/// Authenticate a previously registered user, no authentication required.
 	rpc Auth(AuthRequest) returns (RegisteredUser) {}
+	/// Unregister a new user, authentication required.
 	rpc Unregister(Empty) returns (ErrorCode) {}
+	/// Create a new contract, authentication required.
 	rpc PostContract(PostContractRequest) returns (ErrorCode) {}
+	/// Fetch a previously create contract, authentication required.
 	rpc GetContract(GetContractRequest) returns (Contract) {}
+	/// Join a signature discovery room, authentication required.
+	// The stream is triggered for each new user connected in this channel.
 	rpc JoinSignature(JoinSignatureRequest) returns (stream UserConnected) {}
-	rpc ReadySign(ReadySignRequest) returns (LaunchSignature) {} // Warning, LaunchSignature can be emitted with a very high delay
+	/// Join an ignition room, authentication required.
+	// The response is returned when every signer is ready for a specific contract.
+	// Warning, can me answered with a very high delay.
+	rpc ReadySign(ReadySignRequest) returns (LaunchSignature) {}
 }
 
-// RegisterRequest message contains the client's email adress and his
-// request (ie the PEM-encoded certificate request)
 message RegisterRequest {
+	/// User mail
 	string email = 1;
+	/// Certificate request (CSR) as PEM
 	string request = 2;
 }
 
-// ErrorCode message contains an error code and a message
+/// ErrorCode message contains an error code and a message.
+//
 // Above or zero : target-side error
+//
 // Less than 0   : local error
 message ErrorCode {
 	enum Code {
-		// SUCCESS is the error code for a successful request
+		/// the error code for a successful request
 		SUCCESS = 0;
-		// INVARG is the error code for an invalid argument
+		/// the error code for an invalid argument
 		INVARG = 1;
-		// BADAUTH is the error code for a bad authentication
+		/// the error code for a bad authentication
 		BADAUTH = 2;
-		// WARNING is the error code for a success state containing a specific warning message
+		/// the error code for a success state containing a specific warning message
 		WARNING = 3;
-		// INTERR is the error code for an internal server error
+		/// the error code for an internal server error
 		INTERR = -1;
-		// TIMEOUT is the error code for a timeout or unreacheable target
+		/// the error code for a timeout or unreacheable target
 		TIMEOUT = -2;
 	}
 	Code code = 1;
+	/// An additional message, if needed
 	string message = 2;
 }
 
-// AuthRequest message contains the client's email adress and the token used
-// for authentication
 message AuthRequest {
+	/// User email
 	string email = 1;
+	/// User authentication token
 	string token = 2;
 }
 
-// RegisteredUser message contains the generated client certificate
-// (PEM-encoded)
 message RegisteredUser {
+	/// User certificate, as generated by the platform (PEM)
 	string clientCert = 1;
 }
 
-// Empty message is an empty message
+/// An empty message, used when no parameters are required for a query or an answer.
 message Empty {
 }
 
-// PostContractRequest message contains the contract as SHA-512 hash, its filename,
-// the list of signers as an array of strings, and a comment
 message PostContractRequest {
+	/// Contract SHA-512 hash
 	bytes hash = 1;
+	/// Contract filename
 	string filename = 2;
+	/// List of signers emails
 	repeated string signer = 3;
+	/// Additional comment
 	string comment = 4;
 }
 
-// GetContractRequest message contains the uuid of the asked contract
 message GetContractRequest {
+	/// UUID of the requested contract
 	string uuid = 1;
 }