Documentation is lacking

[edigaryev]

Here's an example of a placement driver service definition:

kvproto/proto/pdpb.proto

Lines 18 to 78 in f7ca9b5

	service PD {
	// GetMembers get the member list of this cluster. It does not require
	// the cluster_id in request matchs the id of this cluster.
	rpc GetMembers(GetMembersRequest) returns (GetMembersResponse) {}
	rpc Tso(stream TsoRequest) returns (stream TsoResponse) {}
	rpc Bootstrap(BootstrapRequest) returns (BootstrapResponse) {}
	rpc IsBootstrapped(IsBootstrappedRequest) returns (IsBootstrappedResponse) {}
	rpc AllocID(AllocIDRequest) returns (AllocIDResponse) {}
	rpc GetStore(GetStoreRequest) returns (GetStoreResponse) {}
	rpc PutStore(PutStoreRequest) returns (PutStoreResponse) {}
	rpc GetAllStores(GetAllStoresRequest) returns (GetAllStoresResponse) {}
	rpc StoreHeartbeat(StoreHeartbeatRequest) returns (StoreHeartbeatResponse) {}
	rpc RegionHeartbeat(stream RegionHeartbeatRequest) returns (stream RegionHeartbeatResponse) {}
	rpc GetRegion(GetRegionRequest) returns (GetRegionResponse) {}
	rpc GetPrevRegion(GetRegionRequest) returns (GetRegionResponse) {}
	rpc GetRegionByID(GetRegionByIDRequest) returns (GetRegionResponse) {}
	rpc ScanRegions(ScanRegionsRequest) returns (ScanRegionsResponse) {}
	rpc AskSplit(AskSplitRequest) returns (AskSplitResponse) {
	// Use AskBatchSplit instead.
	option deprecated = true;
	}
	rpc ReportSplit(ReportSplitRequest) returns (ReportSplitResponse) {
	// Use ResportBatchSplit instead.
	option deprecated = true;
	}
	rpc AskBatchSplit(AskBatchSplitRequest) returns (AskBatchSplitResponse) {}
	rpc ReportBatchSplit(ReportBatchSplitRequest) returns (ReportBatchSplitResponse) {}
	rpc GetClusterConfig(GetClusterConfigRequest) returns (GetClusterConfigResponse) {}
	rpc PutClusterConfig(PutClusterConfigRequest) returns (PutClusterConfigResponse) {}
	rpc ScatterRegion(ScatterRegionRequest) returns (ScatterRegionResponse) {}
	rpc GetGCSafePoint(GetGCSafePointRequest) returns (GetGCSafePointResponse) {}
	rpc UpdateGCSafePoint(UpdateGCSafePointRequest) returns (UpdateGCSafePointResponse) {}
	rpc UpdateServiceGCSafePoint(UpdateServiceGCSafePointRequest) returns (UpdateServiceGCSafePointResponse) {}
	rpc SyncRegions(stream SyncRegionRequest) returns (stream SyncRegionResponse) {}
	rpc GetOperator(GetOperatorRequest) returns (GetOperatorResponse) {}
	}

PD is used by both peers and clients, yet there's not a single comment that gives the reader a clue about which methods are for peers only, which are for clients, nor what each of the methods actually supposed to do.

It would be nice to have Protocol Buffers files documented, especially those that are supposed to be consumed by clients.