proto: Document Diff Service

3 files changed, 199 insertions, 155 deletions

diff --git a/proto/diff.proto b/proto/diff.proto
index f2a961bf6..d140db71c 100644
--- a/proto/diff.proto
+++ b/proto/diff.proto
@@ -11,35 +11,43 @@ option go_package = "gitlab.com/gitlab-org/gitaly/v16/proto/go/gitalypb";
 // introduced between a set of commits.
 service DiffService {
 
-  // CommitDiff returns stream of CommitDiffResponse with patches chunked over messages.
+  // CommitDiff returns a diff between two different commits. The patch data is
+  // chunked across messages and get streamed back to the client.
   rpc CommitDiff(CommitDiffRequest) returns (stream CommitDiffResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // CommitDelta returns a stream so we can divide the response in chunks of deltas.
+  // CommitDelta returns the deltas between two different commits. A delta
+  // includes everthing that changed about a set of paths except for the actual
+  // diff.
   rpc CommitDelta(CommitDeltaRequest) returns (stream CommitDeltaResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // RawDiff ...
+  // RawDiff returns a diff between two commits. The output is the unmodified
+  // output from git-diff(1). This is not to be confused with git-diff(1)'s
+  // --raw mode.
   rpc RawDiff(RawDiffRequest) returns (stream RawDiffResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // RawPatch ...
+  // RawPatch returns a diff between two commits in a formatted patch.The output
+  // is the unmodified output from git-format-patch(1). This is not to be confused with
+  // git-diff(1)'s --raw mode.
   rpc RawPatch(RawPatchRequest) returns (stream RawPatchResponse) {
     option (op_type) = {
       op: ACCESSOR
     };
   }
 
-  // DiffStats ...
+  // DiffStats returns the diff stats between two commits such as number of lines
+  // changed, etc.
   rpc DiffStats(DiffStatsRequest) returns (stream DiffStatsResponse) {
     option (op_type) = {
       op: ACCESSOR
@@ -64,9 +72,9 @@ service DiffService {
   }
 }
 
-// CommitDiffRequest ...
+// CommitDiffRequest is a request for the CommitDiff RPC.
 message CommitDiffRequest {
-  // DiffMode ...
+  // DiffMode determines the type of diff that will be returned.
   enum DiffMode {
     // DEFAULT is the standard diff mode and results in a linewise diff for textfiles.
     DEFAULT = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
@@ -87,40 +95,46 @@ message CommitDiffRequest {
     WHITESPACE_CHANGES_IGNORE_ALL = 2;
   }
 
-  // repository ...
+  // repository is the one from which to get the diff.
   Repository repository = 1 [(target_repository)=true];
-  // left_commit_id ...
+  // left_commit_id is the left commit ID in <left commit>..<right commit>.
   string left_commit_id = 2;
-  // right_commit_id ...
+  // right_commit_id is the right commit ID in <left commit>..<right commit>.
   string right_commit_id = 3;
   // This field is deprecated, use the `whitespace_changes` field instead.
   reserved "ignore_whitespace_change";
   reserved 4;
-  // paths ...
+
+  // paths is a list of paths that limits the diff to those specific paths.
   repeated bytes paths = 5;
-  // collapse_diffs ...
+  // collapse_diffs causes patches to be emptied after safe_max_files,
+  // safe_max_files, or safe_max_lines is reached.
   bool collapse_diffs = 6;
-  // enforce_limits ...
+  // enforce_limits causes parsing of diffs to stop if max_files, max_lines,
+  // or max_bytes is reached.
   bool enforce_limits = 7;
-
-  // max_files ...
-  // The following set of limits are only enforced when enforce_limits == true.
+  // max_files is the maximum number of files in a diff. Once reached, parsing is stopped
+  // if enforce_limits is true.
   int32 max_files = 8;
-  // max_lines ...
+  // max_lines is the maximum number of lines in a diff. Once reached, parsing is stopped
+  // if enforce_limits is true.
   int32 max_lines = 9;
-  // max_bytes ...
+  // max_bytes is the maximum number of bytes in a diff. Once reached, parsing is stopped
+  // if enforce_limits is true.
   int32 max_bytes = 10;
   // max_patch_bytes is the limitation of a single diff patch,
   // patches surpassing this limit are pruned by default.
   // If this is 0 you will get back empty patches.
   int32 max_patch_bytes = 14;
 
-  // safe_max_files...
-  // These limits are only enforced if collapse_diffs == true.
+  // safe_max_files is the maximum number of files in a diff. Once reached, patches are emptied if
+  // collapse_diffs is true.
   int32 safe_max_files = 11;
-  // safe_max_lines ...
+  // safe_max_lines is the maximum number of lines in a diff. Once reached, patches are emptied if
+  // collapse_diffs is true.
   int32 safe_max_lines = 12;
-  // safe_max_bytes ...
+  // safe_max_bytes is the maximum number of bytes in a diff. Once reached, patches are emptied if
+  // collapse_diffs is true.
   int32 safe_max_bytes = 13;
 
   // diff_mode is the mode used for generating the diff. Please refer to the enum declaration for supported modes.
@@ -147,23 +161,23 @@ message CommitDiffRequest {
 message CommitDiffResponse {
   reserved 8;
 
-  // from_path ...
+  // from_path is the path that to_path is getting compared to.
   bytes from_path = 1;
-  // to_path ...
+  // to_path is the path that from_path is getting compared against.
   bytes to_path = 2;
-  // from_id is the blob ID as returned via `git diff --full-index`.
+  // from_id is the id of the blob that is getting compared against.
   string from_id = 3;
-  // to_id ...
+  // to_id is the id of the blob that is getting compared to.
   string to_id = 4;
-  // old_mode ...
+  // old_mode is the mode of the file getting compared against.
   int32 old_mode = 5;
-  // new_mode ...
+  // new_mode is the mode of the file getting compared to.
   int32 new_mode = 6;
-  // binary ...
+  // binary indicates whether or not binary data is getting compared.
   bool binary = 7;
-  // raw_patch_data ...
+  // raw_patch_data is the unparsed data of the diff.
   bytes raw_patch_data = 9;
-  // end_of_patch ...
+  // end_of_patch indicates if this message represents the end of the diff.
   bool end_of_patch = 10;
   // overflow_marker Indicates if the diff file exceeded limitations, in which case
   // there will be no patch data sent, only information about the patch.
@@ -176,97 +190,100 @@ message CommitDiffResponse {
   bool too_large = 13;
 }
 
-// CommitDeltaRequest ...
+// CommitDeltaRequest is a request for the CommitDelta RPC.
 message CommitDeltaRequest {
-  // repository ...
+  // repository is the one to get the commit deltas from.
   Repository repository = 1 [(target_repository)=true];
-  // left_commit_id ...
+  // left_commit_id is the left commit ID in <left commit>..<right commit>.
   string left_commit_id = 2;
-  // right_commit_id ...
+  // right_commit_id is the right commit ID in <left commit>..<right commit>.
   string right_commit_id = 3;
-  // paths ...
+  // paths is a list of paths that limits the diff to those specific paths.
   repeated bytes paths = 4;
 }
 
-// CommitDelta ...
+// CommitDelta represents the metadata of a diff between two commits without the actual
+// patch data.
 message CommitDelta {
-  // from_path ...
+  // from_path is the path that to_path is getting compared to.
   bytes from_path = 1;
-  // to_path ...
+  // to_path is the path that from_path is getting compared against.
   bytes to_path = 2;
-  // from_id is the blob ID as returned via `git diff --full-index`.
+  // from_id is the id of the blob that is getting compared to.
   string from_id = 3;
-  // to_id ...
+  // to_id is the id of the blob that is getting compared against.
   string to_id = 4;
-  // old_mode ...
+  // old_mode is the mode of the blob getting compared against.
   int32 old_mode = 5;
-  // new_mode ...
+  // new_mode is the mode of the blob getting compared to.
   int32 new_mode = 6;
 }
 
-// CommitDeltaResponse ...
+// CommitDeltaResponse is the response from a CommitDelta RPC call.
 message CommitDeltaResponse {
-  // deltas ...
+  // deltas is a list of CommitDeltas
   repeated CommitDelta deltas = 1;
 }
 
-// RawDiffRequest ...
+// RawDiffRequest is a request for the RawDiff RPC.
 message RawDiffRequest {
-  // repository ...
+  // repository is the one to get the diff from.
   Repository repository = 1 [(target_repository)=true];
-  // left_commit_id ...
+  // left_commit_id is the left commit ID in <left commit>..<right commit>.
   string left_commit_id = 2;
-  // right_commit_id ...
+  // right_commit_id is the right commit ID in <left commit>..<right commit>.
   string right_commit_id = 3;
 }
 
-// RawDiffResponse ...
+// RawDiffResponse is a response for the RawDiff RPC.
 message RawDiffResponse {
-  // data ...
+  // data is a sequence of bytes representing the unmodified diff patch data
+  // returned from git-diff(1).
   bytes data = 1;
 }
 
-// RawPatchRequest ...
+// RawPatchRequest is a response for the RawPatch RPC.
 message RawPatchRequest {
-  // repository ...
+  // repository is the one to get the patch from.
   Repository repository = 1 [(target_repository)=true];
-  // left_commit_id ...
+  // left_commit_id is the left commit ID in <left commit>..<right commit>.
   string left_commit_id = 2;
-  // right_commit_id ...
+  // right_commit_id is the right commit ID in <left commit>..<right commit>
   string right_commit_id = 3;
 }
 
-// RawPatchResponse ...
+// RawPatchResponse is a reponse for the RawPatch RPC.
 message RawPatchResponse {
-  // data ...
+  // data is a sequence of bytes representing the unmodified diff patch data
+  // returned from git-format-patch(1).
   bytes data = 1;
 }
 
-// DiffStatsRequest ...
+// DiffStatsRequest is a request for the DiffStats RPC.
 message DiffStatsRequest {
-  // repository ...
+  // repository is the one to get diff stats from.
   Repository repository = 1 [(target_repository)=true];
-  // left_commit_id ...
+  // left_commit_id is the left commit ID in <left commit>..<right commit>
   string left_commit_id = 2;
-  // right_commit_id ...
+  // right_commit_id is the right commit ID in <left commit>..<right commit>
   string right_commit_id = 3;
 }
 
-// DiffStats ...
+// DiffStats represents diff statistics for a path.
 message DiffStats {
-  // path ...
+  // path is the path of the change.
   bytes path = 1;
-  // additions ...
+  // additions is the number of additions in a diff.
   int32 additions = 2;
-  // deletions ...
-  int32 deletions = 3;
-  // old_path ...
+  // deletions is the number of deletions in a diff.
+  int32 deletions = 3; 
+  // old_path is the original path in the event of a rename.
   bytes old_path = 4;
 }
 
-// DiffStatsResponse ...
+// DiffStatsResponse is a response for the DiffStats RPC.
 message DiffStatsResponse {
-  // stats ...
+  // stats is a list of DiffStats.
   repeated DiffStats stats = 1;
 }
 
@@ -343,15 +360,16 @@ message FindChangedPathsResponse {
   repeated ChangedPaths paths = 1;
 }
 
-// ChangedPaths includes the path of the file, and the status of the change.
+// ChangedPaths contains information about a changed file. It includes the path
+// of the file, and the status of the change.
 message ChangedPaths {
-  // Status ...
+  // Status is an enum representing the type of change.
   enum Status {
-    // ADDED ...
+    // ADDED indicates a file was added.
     ADDED = 0; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
-    // MODIFIED ...
+    // MODIFIED indicates a file was modified.
     MODIFIED = 1; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-    // DELETED ...
+    // DELETED indicates a file was deleted.
     DELETED = 2; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
     // TYPE_CHANGE ...
     TYPE_CHANGE = 3; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
@@ -359,9 +377,9 @@ message ChangedPaths {
     COPIED = 4; // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
   }
 
-  // path ...
+  // path is the path of the change in question.
   bytes path = 1;
-  // status ...
+  // status is the type of change.
   Status status = 2;
   // old_mode is the mode of the changed path previous to the change. May be one of the following values:
   //
diff --git a/proto/go/gitalypb/diff.pb.go b/proto/go/gitalypb/diff.pb.go
index 275cccadf..c34c019eb 100644
--- a/proto/go/gitalypb/diff.pb.go
+++ b/proto/go/gitalypb/diff.pb.go
@@ -20,7 +20,7 @@ const (
 	_ = protoimpl.EnforceVersion(protoimpl.MaxVersion - 20)
 )
 
-// DiffMode ...
+// DiffMode determines the type of diff that will be returned.
 type CommitDiffRequest_DiffMode int32
 
 const (
@@ -182,15 +182,15 @@ func (FindChangedPathsRequest_MergeCommitDiffMode) EnumDescriptor() ([]byte, []i
 	return file_diff_proto_rawDescGZIP(), []int{12, 0}
 }
 
-// Status ...
+// Status is an enum representing the type of change.
 type ChangedPaths_Status int32
 
 const (
-	// ADDED ...
+	// ADDED indicates a file was added.
 	ChangedPaths_ADDED ChangedPaths_Status = 0 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX ENUM_FIELD_NAMES_ZERO_VALUE_END_WITH
-	// MODIFIED ...
+	// MODIFIED indicates a file was modified.
 	ChangedPaths_MODIFIED ChangedPaths_Status = 1 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
-	// DELETED ...
+	// DELETED indicates a file was deleted.
 	ChangedPaths_DELETED ChangedPaths_Status = 2 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
 	// TYPE_CHANGE ...
 	ChangedPaths_TYPE_CHANGE ChangedPaths_Status = 3 // protolint:disable:this ENUM_FIELD_NAMES_PREFIX
@@ -243,41 +243,47 @@ func (ChangedPaths_Status) EnumDescriptor() ([]byte, []int) {
 	return file_diff_proto_rawDescGZIP(), []int{14, 0}
 }
 
-// CommitDiffRequest ...
+// CommitDiffRequest is a request for the CommitDiff RPC.
 type CommitDiffRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository ...
+	// repository is the one from which to get the diff.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// left_commit_id ...
+	// left_commit_id is the left commit ID in <left commit>..<right commit>.
 	LeftCommitId string `protobuf:"bytes,2,opt,name=left_commit_id,json=leftCommitId,proto3" json:"left_commit_id,omitempty"`
-	// right_commit_id ...
+	// right_commit_id is the right commit ID in <left commit>..<right commit>.
 	RightCommitId string `protobuf:"bytes,3,opt,name=right_commit_id,json=rightCommitId,proto3" json:"right_commit_id,omitempty"`
-	// paths ...
+	// paths is a list of paths that limits the diff to those specific paths.
 	Paths [][]byte `protobuf:"bytes,5,rep,name=paths,proto3" json:"paths,omitempty"`
-	// collapse_diffs ...
+	// collapse_diffs causes patches to be emptied after safe_max_files,
+	// safe_max_files, or safe_max_lines is reached.
 	CollapseDiffs bool `protobuf:"varint,6,opt,name=collapse_diffs,json=collapseDiffs,proto3" json:"collapse_diffs,omitempty"`
-	// enforce_limits ...
+	// enforce_limits causes parsing of diffs to stop if max_files, max_lines,
+	// or max_bytes is reached.
 	EnforceLimits bool `protobuf:"varint,7,opt,name=enforce_limits,json=enforceLimits,proto3" json:"enforce_limits,omitempty"`
-	// max_files ...
-	// The following set of limits are only enforced when enforce_limits == true.
+	// max_files is the maximum number of files in a diff. Once reached, parsing is stopped
+	// if enforce_limits is true.
 	MaxFiles int32 `protobuf:"varint,8,opt,name=max_files,json=maxFiles,proto3" json:"max_files,omitempty"`
-	// max_lines ...
+	// max_lines is the maximum number of lines in a diff. Once reached, parsing is stopped
+	// if enforce_limits is true.
 	MaxLines int32 `protobuf:"varint,9,opt,name=max_lines,json=maxLines,proto3" json:"max_lines,omitempty"`
-	// max_bytes ...
+	// max_bytes is the maximum number of bytes in a diff. Once reached, parsing is stopped
+	// if enforce_limits is true.
 	MaxBytes int32 `protobuf:"varint,10,opt,name=max_bytes,json=maxBytes,proto3" json:"max_bytes,omitempty"`
 	// max_patch_bytes is the limitation of a single diff patch,
 	// patches surpassing this limit are pruned by default.
 	// If this is 0 you will get back empty patches.
 	MaxPatchBytes int32 `protobuf:"varint,14,opt,name=max_patch_bytes,json=maxPatchBytes,proto3" json:"max_patch_bytes,omitempty"`
-	// safe_max_files...
-	// These limits are only enforced if collapse_diffs == true.
+	// safe_max_files is the maximum number of files in a diff. Once reached, patches are emptied if
+	// collapse_diffs is true.
 	SafeMaxFiles int32 `protobuf:"varint,11,opt,name=safe_max_files,json=safeMaxFiles,proto3" json:"safe_max_files,omitempty"`
-	// safe_max_lines ...
+	// safe_max_lines is the maximum number of lines in a diff. Once reached, patches are emptied if
+	// collapse_diffs is true.
 	SafeMaxLines int32 `protobuf:"varint,12,opt,name=safe_max_lines,json=safeMaxLines,proto3" json:"safe_max_lines,omitempty"`
-	// safe_max_bytes ...
+	// safe_max_bytes is the maximum number of bytes in a diff. Once reached, patches are emptied if
+	// collapse_diffs is true.
 	SafeMaxBytes int32 `protobuf:"varint,13,opt,name=safe_max_bytes,json=safeMaxBytes,proto3" json:"safe_max_bytes,omitempty"`
 	// diff_mode is the mode used for generating the diff. Please refer to the enum declaration for supported modes.
 	DiffMode CommitDiffRequest_DiffMode `protobuf:"varint,15,opt,name=diff_mode,json=diffMode,proto3,enum=gitaly.CommitDiffRequest_DiffMode" json:"diff_mode,omitempty"`
@@ -453,23 +459,23 @@ type CommitDiffResponse struct {
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// from_path ...
+	// from_path is the path that to_path is getting compared to.
 	FromPath []byte `protobuf:"bytes,1,opt,name=from_path,json=fromPath,proto3" json:"from_path,omitempty"`
-	// to_path ...
+	// to_path is the path that from_path is getting compared against.
 	ToPath []byte `protobuf:"bytes,2,opt,name=to_path,json=toPath,proto3" json:"to_path,omitempty"`
-	// from_id is the blob ID as returned via `git diff --full-index`.
+	// from_id is the id of the blob that is getting compared against.
 	FromId string `protobuf:"bytes,3,opt,name=from_id,json=fromId,proto3" json:"from_id,omitempty"`
-	// to_id ...
+	// to_id is the id of the blob that is getting compared to.
 	ToId string `protobuf:"bytes,4,opt,name=to_id,json=toId,proto3" json:"to_id,omitempty"`
-	// old_mode ...
+	// old_mode is the mode of the file getting compared against.
 	OldMode int32 `protobuf:"varint,5,opt,name=old_mode,json=oldMode,proto3" json:"old_mode,omitempty"`
-	// new_mode ...
+	// new_mode is the mode of the file getting compared to.
 	NewMode int32 `protobuf:"varint,6,opt,name=new_mode,json=newMode,proto3" json:"new_mode,omitempty"`
-	// binary ...
+	// binary indicates whether or not binary data is getting compared.
 	Binary bool `protobuf:"varint,7,opt,name=binary,proto3" json:"binary,omitempty"`
-	// raw_patch_data ...
+	// raw_patch_data is the unparsed data of the diff.
 	RawPatchData []byte `protobuf:"bytes,9,opt,name=raw_patch_data,json=rawPatchData,proto3" json:"raw_patch_data,omitempty"`
-	// end_of_patch ...
+	// end_of_patch indicates if this message represents the end of the diff.
 	EndOfPatch bool `protobuf:"varint,10,opt,name=end_of_patch,json=endOfPatch,proto3" json:"end_of_patch,omitempty"`
 	// overflow_marker Indicates if the diff file exceeded limitations, in which case
 	// there will be no patch data sent, only information about the patch.
@@ -598,19 +604,19 @@ func (x *CommitDiffResponse) GetTooLarge() bool {
 	return false
 }
 
-// CommitDeltaRequest ...
+// CommitDeltaRequest is a request for the CommitDelta RPC.
 type CommitDeltaRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository ...
+	// repository is the one to get the commit deltas from.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// left_commit_id ...
+	// left_commit_id is the left commit ID in <left commit>..<right commit>.
 	LeftCommitId string `protobuf:"bytes,2,opt,name=left_commit_id,json=leftCommitId,proto3" json:"left_commit_id,omitempty"`
-	// right_commit_id ...
+	// right_commit_id is the right commit ID in <left commit>..<right commit>.
 	RightCommitId string `protobuf:"bytes,3,opt,name=right_commit_id,json=rightCommitId,proto3" json:"right_commit_id,omitempty"`
-	// paths ...
+	// paths is a list of paths that limits the diff to those specific paths.
 	Paths [][]byte `protobuf:"bytes,4,rep,name=paths,proto3" json:"paths,omitempty"`
 }
 
@@ -674,23 +680,24 @@ func (x *CommitDeltaRequest) GetPaths() [][]byte {
 	return nil
 }
 
-// CommitDelta ...
+// CommitDelta represents the metadata of a diff between two commits without the actual
+// patch data.
 type CommitDelta struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// from_path ...
+	// from_path is the path that to_path is getting compared to.
 	FromPath []byte `protobuf:"bytes,1,opt,name=from_path,json=fromPath,proto3" json:"from_path,omitempty"`
-	// to_path ...
+	// to_path is the path that from_path is getting compared against.
 	ToPath []byte `protobuf:"bytes,2,opt,name=to_path,json=toPath,proto3" json:"to_path,omitempty"`
-	// from_id is the blob ID as returned via `git diff --full-index`.
+	// from_id is the id of the blob that is getting compared to.
 	FromId string `protobuf:"bytes,3,opt,name=from_id,json=fromId,proto3" json:"from_id,omitempty"`
-	// to_id ...
+	// to_id is the id of the blob that is getting compared against.
 	ToId string `protobuf:"bytes,4,opt,name=to_id,json=toId,proto3" json:"to_id,omitempty"`
-	// old_mode ...
+	// old_mode is the mode of the blob getting compared against.
 	OldMode int32 `protobuf:"varint,5,opt,name=old_mode,json=oldMode,proto3" json:"old_mode,omitempty"`
-	// new_mode ...
+	// new_mode is the mode of the blob getting compared to.
 	NewMode int32 `protobuf:"varint,6,opt,name=new_mode,json=newMode,proto3" json:"new_mode,omitempty"`
 }
 
@@ -768,13 +775,13 @@ func (x *CommitDelta) GetNewMode() int32 {
 	return 0
 }
 
-// CommitDeltaResponse ...
+// CommitDeltaResponse is the response from a CommitDelta RPC call.
 type CommitDeltaResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// deltas ...
+	// deltas is a list of CommitDeltas
 	Deltas []*CommitDelta `protobuf:"bytes,1,rep,name=deltas,proto3" json:"deltas,omitempty"`
 }
 
@@ -817,17 +824,17 @@ func (x *CommitDeltaResponse) GetDeltas() []*CommitDelta {
 	return nil
 }
 
-// RawDiffRequest ...
+// RawDiffRequest is a request for the RawDiff RPC.
 type RawDiffRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository ...
+	// repository is the one to get the diff from.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// left_commit_id ...
+	// left_commit_id is the left commit ID in <left commit>..<right commit>.
 	LeftCommitId string `protobuf:"bytes,2,opt,name=left_commit_id,json=leftCommitId,proto3" json:"left_commit_id,omitempty"`
-	// right_commit_id ...
+	// right_commit_id is the right commit ID in <left commit>..<right commit>.
 	RightCommitId string `protobuf:"bytes,3,opt,name=right_commit_id,json=rightCommitId,proto3" json:"right_commit_id,omitempty"`
 }
 
@@ -884,13 +891,14 @@ func (x *RawDiffRequest) GetRightCommitId() string {
 	return ""
 }
 
-// RawDiffResponse ...
+// RawDiffResponse is a response for the RawDiff RPC.
 type RawDiffResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// data ...
+	// data is a sequence of bytes representing the unmodified diff patch data
+	// returned from git-diff(1).
 	Data []byte `protobuf:"bytes,1,opt,name=data,proto3" json:"data,omitempty"`
 }
 
@@ -933,17 +941,17 @@ func (x *RawDiffResponse) GetData() []byte {
 	return nil
 }
 
-// RawPatchRequest ...
+// RawPatchRequest is a response for the RawPatch RPC.
 type RawPatchRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository ...
+	// repository is the one to get the patch from.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// left_commit_id ...
+	// left_commit_id is the left commit ID in <left commit>..<right commit>.
 	LeftCommitId string `protobuf:"bytes,2,opt,name=left_commit_id,json=leftCommitId,proto3" json:"left_commit_id,omitempty"`
-	// right_commit_id ...
+	// right_commit_id is the right commit ID in <left commit>..<right commit>
 	RightCommitId string `protobuf:"bytes,3,opt,name=right_commit_id,json=rightCommitId,proto3" json:"right_commit_id,omitempty"`
 }
 
@@ -1000,13 +1008,14 @@ func (x *RawPatchRequest) GetRightCommitId() string {
 	return ""
 }
 
-// RawPatchResponse ...
+// RawPatchResponse is a reponse for the RawPatch RPC.
 type RawPatchResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// data ...
+	// data is a sequence of bytes representing the unmodified diff patch data
+	// returned from git-format-patch(1).
 	Data []byte `protobuf:"bytes,1,opt,name=data,proto3" json:"data,omitempty"`
 }
 
@@ -1049,17 +1058,17 @@ func (x *RawPatchResponse) GetData() []byte {
 	return nil
 }
 
-// DiffStatsRequest ...
+// DiffStatsRequest is a request for the DiffStats RPC.
 type DiffStatsRequest struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// repository ...
+	// repository is the one to get diff stats from.
 	Repository *Repository `protobuf:"bytes,1,opt,name=repository,proto3" json:"repository,omitempty"`
-	// left_commit_id ...
+	// left_commit_id is the left commit ID in <left commit>..<right commit>
 	LeftCommitId string `protobuf:"bytes,2,opt,name=left_commit_id,json=leftCommitId,proto3" json:"left_commit_id,omitempty"`
-	// right_commit_id ...
+	// right_commit_id is the right commit ID in <left commit>..<right commit>
 	RightCommitId string `protobuf:"bytes,3,opt,name=right_commit_id,json=rightCommitId,proto3" json:"right_commit_id,omitempty"`
 }
 
@@ -1116,19 +1125,19 @@ func (x *DiffStatsRequest) GetRightCommitId() string {
 	return ""
 }
 
-// DiffStats ...
+// DiffStats represents diff statistics for a path.
 type DiffStats struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// path ...
+	// path is the path of the change.
 	Path []byte `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`
-	// additions ...
+	// additions is the number of additions in a diff.
 	Additions int32 `protobuf:"varint,2,opt,name=additions,proto3" json:"additions,omitempty"`
-	// deletions ...
+	// deletions is the number of deletions in a diff.
 	Deletions int32 `protobuf:"varint,3,opt,name=deletions,proto3" json:"deletions,omitempty"`
-	// old_path ...
+	// old_path is the original path in the event of a rename.
 	OldPath []byte `protobuf:"bytes,4,opt,name=old_path,json=oldPath,proto3" json:"old_path,omitempty"`
 }
 
@@ -1192,13 +1201,13 @@ func (x *DiffStats) GetOldPath() []byte {
 	return nil
 }
 
-// DiffStatsResponse ...
+// DiffStatsResponse is a response for the DiffStats RPC.
 type DiffStatsResponse struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// stats ...
+	// stats is a list of DiffStats.
 	Stats []*DiffStats `protobuf:"bytes,1,rep,name=stats,proto3" json:"stats,omitempty"`
 }
 
@@ -1377,15 +1386,16 @@ func (x *FindChangedPathsResponse) GetPaths() []*ChangedPaths {
 	return nil
 }
 
-// ChangedPaths includes the path of the file, and the status of the change.
+// ChangedPaths contains information about a changed file. It includes the path
+// of the file, and the status of the change.
 type ChangedPaths struct {
 	state         protoimpl.MessageState
 	sizeCache     protoimpl.SizeCache
 	unknownFields protoimpl.UnknownFields
 
-	// path ...
+	// path is the path of the change in question.
 	Path []byte `protobuf:"bytes,1,opt,name=path,proto3" json:"path,omitempty"`
-	// status ...
+	// status is the type of change.
 	Status ChangedPaths_Status `protobuf:"varint,2,opt,name=status,proto3,enum=gitaly.ChangedPaths_Status" json:"status,omitempty"`
 	// old_mode is the mode of the changed path previous to the change. May be one of the following values:
 	//
diff --git a/proto/go/gitalypb/diff_grpc.pb.go b/proto/go/gitalypb/diff_grpc.pb.go
index 3e53571a6..a16c0e63e 100644
--- a/proto/go/gitalypb/diff_grpc.pb.go
+++ b/proto/go/gitalypb/diff_grpc.pb.go
@@ -22,15 +22,23 @@ const _ = grpc.SupportPackageIsVersion7
 //
 // For semantics around ctx use and closing/ending streaming RPCs, please refer to https://pkg.go.dev/google.golang.org/grpc/?tab=doc#ClientConn.NewStream.
 type DiffServiceClient interface {
-	// CommitDiff returns stream of CommitDiffResponse with patches chunked over messages.
+	// CommitDiff returns a diff between two different commits. The patch data is
+	// chunked across messages and get streamed back to the client.
 	CommitDiff(ctx context.Context, in *CommitDiffRequest, opts ...grpc.CallOption) (DiffService_CommitDiffClient, error)
-	// CommitDelta returns a stream so we can divide the response in chunks of deltas.
+	// CommitDelta returns the deltas between two different commits. A delta
+	// includes everthing that changed about a set of paths except for the actual
+	// diff.
 	CommitDelta(ctx context.Context, in *CommitDeltaRequest, opts ...grpc.CallOption) (DiffService_CommitDeltaClient, error)
-	// RawDiff ...
+	// RawDiff returns a diff between two commits. The output is the unmodified
+	// output from git-diff(1). This is not to be confused with git-diff(1)'s
+	// --raw mode.
 	RawDiff(ctx context.Context, in *RawDiffRequest, opts ...grpc.CallOption) (DiffService_RawDiffClient, error)
-	// RawPatch ...
+	// RawPatch returns a diff between two commits in a formatted patch.The output
+	// is the unmodified output from git-format-patch(1). This is not to be confused with
+	// git-diff(1)'s --raw mode.
 	RawPatch(ctx context.Context, in *RawPatchRequest, opts ...grpc.CallOption) (DiffService_RawPatchClient, error)
-	// DiffStats ...
+	// DiffStats returns the diff stats between two commits such as number of lines
+	// changed, etc.
 	DiffStats(ctx context.Context, in *DiffStatsRequest, opts ...grpc.CallOption) (DiffService_DiffStatsClient, error)
 	// FindChangedPaths returns a list of files changed along with the status of each file
 	FindChangedPaths(ctx context.Context, in *FindChangedPathsRequest, opts ...grpc.CallOption) (DiffService_FindChangedPathsClient, error)
@@ -254,15 +262,23 @@ func (c *diffServiceClient) GetPatchID(ctx context.Context, in *GetPatchIDReques
 // All implementations must embed UnimplementedDiffServiceServer
 // for forward compatibility
 type DiffServiceServer interface {
-	// CommitDiff returns stream of CommitDiffResponse with patches chunked over messages.
+	// CommitDiff returns a diff between two different commits. The patch data is
+	// chunked across messages and get streamed back to the client.
 	CommitDiff(*CommitDiffRequest, DiffService_CommitDiffServer) error
-	// CommitDelta returns a stream so we can divide the response in chunks of deltas.
+	// CommitDelta returns the deltas between two different commits. A delta
+	// includes everthing that changed about a set of paths except for the actual
+	// diff.
 	CommitDelta(*CommitDeltaRequest, DiffService_CommitDeltaServer) error
-	// RawDiff ...
+	// RawDiff returns a diff between two commits. The output is the unmodified
+	// output from git-diff(1). This is not to be confused with git-diff(1)'s
+	// --raw mode.
 	RawDiff(*RawDiffRequest, DiffService_RawDiffServer) error
-	// RawPatch ...
+	// RawPatch returns a diff between two commits in a formatted patch.The output
+	// is the unmodified output from git-format-patch(1). This is not to be confused with
+	// git-diff(1)'s --raw mode.
 	RawPatch(*RawPatchRequest, DiffService_RawPatchServer) error
-	// DiffStats ...
+	// DiffStats returns the diff stats between two commits such as number of lines
+	// changed, etc.
 	DiffStats(*DiffStatsRequest, DiffService_DiffStatsServer) error
 	// FindChangedPaths returns a list of files changed along with the status of each file
 	FindChangedPaths(*FindChangedPathsRequest, DiffService_FindChangedPathsServer) error