From f5451a34bc463091fede777d3a21e905b589cc67 Mon Sep 17 00:00:00 2001 From: Jeremy Fitzhardinge Date: Thu, 30 Sep 2021 09:40:23 -0700 Subject: [PATCH] scs: turn all comments into doc comments Summary: Use `///` for comments so they're converted into doc comments so that they'll be rendered in the Rust docs (eg https://www.internalfb.com/intern/rustdoc/eden/mononoke/scs/if:source_control-rust/source_control/client/trait.SourceControlService.html, or hover docs in vs code). It's already pretty well documented, so it would be nice to take advantage of it. Reviewed By: krallin Differential Revision: D31288804 fbshipit-source-id: 9f2b3e0966832791c6ce39574cafdc71f8c032dd --- eden/mononoke/scs/if/source_control.thrift | 1116 ++++++++++---------- 1 file changed, 558 insertions(+), 558 deletions(-) diff --git a/eden/mononoke/scs/if/source_control.thrift b/eden/mononoke/scs/if/source_control.thrift index 52c896e368..f89e83276e 100644 --- a/eden/mononoke/scs/if/source_control.thrift +++ b/eden/mononoke/scs/if/source_control.thrift @@ -14,86 +14,86 @@ namespace py scm.service.thrift.source_control namespace py3 scm.service.thrift struct DateTime { - // UNIX timestamp + /// UNIX timestamp 1: required i64 timestamp; - // Time zone offsets in minutes + /// Time zone offsets in minutes 2: required i32 tz; } -// Specifiers -// -// Specifiers are used in each call to identify entities within source control. +/// Specifiers +/// +/// Specifiers are used in each call to identify entities within source control. struct RepoSpecifier { - // The name of the repository. + /// The name of the repository. 1: string name; } -// The schemes by which commits can be identified. +/// The schemes by which commits can be identified. enum CommitIdentityScheme { UNKNOWN = 0, - // Commits are identified by the 32-byte hash of Mononoke's bonsai - // changeset. + /// Commits are identified by the 32-byte hash of Mononoke's bonsai + /// changeset. BONSAI = 1, - // Commits are identified by the 20-byte hash of the Mercurial commit. + /// Commits are identified by the 20-byte hash of the Mercurial commit. HG = 2, - // Commits are identified by the 20-byte hash of the Git commit. + /// Commits are identified by the 20-byte hash of the Git commit. GIT = 3, - // Commits are identified by an externally-assigned repo-wide unique - // integer. + /// Commits are identified by an externally-assigned repo-wide unique + /// integer. GLOBALREV = 4, - // Commits identified by integer svn revision number. + /// Commits identified by integer svn revision number. SVNREV = 5, } -// A unique identifier for a commit. -// -// Commit hashes are represented using raw binary, not as hex-encoded strings. -// If you have a hex-encoded string hash you must convert it to binary, for -// example using: -// -// - In Rust: `faster_hex::hex_decode` -// - In Python: `bytes.fromhex` -// - In PHP/Hack: `Str::hex2bin` +/// A unique identifier for a commit. +/// +/// Commit hashes are represented using raw binary, not as hex-encoded strings. +/// If you have a hex-encoded string hash you must convert it to binary, for +/// example using: +/// +/// - In Rust: `faster_hex::hex_decode` +/// - In Python: `bytes.fromhex` +/// - In PHP/Hack: `Str::hex2bin` union CommitId { - // Commit identified by the hash of Mononoke's bonsai changeset. + /// Commit identified by the hash of Mononoke's bonsai changeset. 1: binary bonsai; - // Commit identified by the hash of the Mercurial commit. + /// Commit identified by the hash of the Mercurial commit. 2: binary hg; - // Commit identified by the hash of the Git commit. + /// Commit identified by the hash of the Git commit. 3: binary git; - // Commit identified by an externally-assigned repo-wide unique integer. + /// Commit identified by an externally-assigned repo-wide unique integer. 4: i64 globalrev; - // Commit identified by svn revision number. + /// Commit identified by svn revision number. 5: i64 svnrev; } -// Specified a commit within a repo. +/// Specified a commit within a repo. struct CommitSpecifier { - // The repository that contains the commit. + /// The repository that contains the commit. 1: RepoSpecifier repo; 2: CommitId id; } -// The UTF-8 path of the file or directory. +/// The UTF-8 path of the file or directory. typedef string Path -// Specifies a file or directory within a commit. +/// Specifies a file or directory within a commit. struct CommitPathSpecifier { - // The commit within which the file or directory is found. + /// The commit within which the file or directory is found. 1: CommitSpecifier commit; - // The UTF-8 path of the file or directory. + /// The UTF-8 path of the file or directory. 2: Path path; } @@ -101,146 +101,146 @@ struct CommitMultiplePathInfoParams { 1: list paths; } -// Specifies a tree by its ID. +/// Specifies a tree by its ID. struct TreeIdSpecifier { - // The repository that contains the tree. + /// The repository that contains the tree. 1: RepoSpecifier repo; - // The ID of the tree, obtained from a previous call to the service. + /// The ID of the tree, obtained from a previous call to the service. 2: binary id; } union TreeSpecifier { - // Specify a tree by its path in a commit. + /// Specify a tree by its path in a commit. 1: CommitPathSpecifier by_commit_path; - // Specify a tree by its id. + /// Specify a tree by its id. 2: TreeIdSpecifier by_id; } -// Specifies a file by its ID. +/// Specifies a file by its ID. struct FileIdSpecifier { - // The repository that contains the file. + /// The repository that contains the file. 1: RepoSpecifier repo; - // The ID of the file, obtained from a previous call to the service. + /// The ID of the file, obtained from a previous call to the service. 2: binary id; } -// Specifies a file by its content hash. +/// Specifies a file by its content hash. struct FileContentHashSpecifier { - // The repository that contains the file. + /// The repository that contains the file. 1: RepoSpecifier repo; - // The content hash of the file. + /// The content hash of the file. 2: binary content_hash; } union FileSpecifier { - // Specify a file by its path in a commit. + /// Specify a file by its path in a commit. 1: CommitPathSpecifier by_commit_path; - // Specify a file by its id. + /// Specify a file by its id. 2: FileIdSpecifier by_id; - // Specify a file by its SHA-1 content hash. + /// Specify a file by its SHA-1 content hash. 3: FileContentHashSpecifier by_sha1_content_hash; - // Specify a file by its SHA-256 content hash. + /// Specify a file by its SHA-256 content hash. 4: FileContentHashSpecifier by_sha256_content_hash; } -// Returned objects +/// Returned objects struct Repo { 1: string name; } struct CommitInfo { - // The IDs of the commit in the requested identity schemes. + /// The IDs of the commit in the requested identity schemes. 2: map ids; - // The commit message. + /// The commit message. 3: string message; - // The date the commit was authored. + /// The date the commit was authored. 4: i64 date; - // The timezone the commit was authored in, in seconds after UTC. + /// The timezone the commit was authored in, in seconds after UTC. 8: i32 tz; - // The author of the commit. + /// The author of the commit. 5: string author; - // The parents of the commit, in the requested identity schemes. + /// The parents of the commit, in the requested identity schemes. 6: list> parents; - // Length of longest path between this commit and any root. + /// Length of longest path between this commit and any root. 9: i64 generation; - // Extra metadata about the commit. + /// Extra metadata about the commit. 7: map extra; } enum EntryType { - // Unknown type + /// Unknown type UNKNOWN = 0, - // Normal file + /// Normal file FILE = 1, - // Executable file + /// Executable file EXEC = 2, - // Symbolic link + /// Symbolic link LINK = 3, - // Sub-directory + /// Sub-directory TREE = 4, } struct FileInfo { - // The id of the file contents that can be used in subsequent look-ups. + /// The id of the file contents that can be used in subsequent look-ups. 1: binary id; - // The size of the file, or the length of the link target path for links. + /// The size of the file, or the length of the link target path for links. 2: i64 file_size; - // The content sha1 of the file. + /// The content sha1 of the file. 3: binary content_sha1; - // The content sha256 of the file. + /// The content sha256 of the file. 4: binary content_sha256; } struct TreeInfo { - // The id of the tree that can be used in subsequent look-ups. + /// The id of the tree that can be used in subsequent look-ups. 1: binary id; - // The sha1 of the simple format of the directory. + /// The sha1 of the simple format of the directory. 2: binary simple_format_sha1; - // The sha256 of the simple format of the directory. + /// The sha256 of the simple format of the directory. 3: binary simple_format_sha256; - // The count of files inside the directory (excluding files inside - // subdirectories). + /// The count of files inside the directory (excluding files inside + /// subdirectories). 4: i64 child_files_count; - // The total size of the files inside the directory (excluding files - // inside subdirectories). + /// The total size of the files inside the directory (excluding files + /// inside subdirectories). 5: i64 child_files_total_size; - // The count of subdirectories inside the directory (excluding - // directories inside subdirectories). + /// The count of subdirectories inside the directory (excluding + /// directories inside subdirectories). 6: i64 child_dirs_count; - // The count of all files in the directory (including files in - // subdirectories). + /// The count of all files in the directory (including files in + /// subdirectories). 7: i64 descendant_files_count; - // The total size of all files in the directory (including files in - // subdirectories). + /// The total size of all files in the directory (including files in + /// subdirectories). 8: i64 descendant_files_total_size; } @@ -250,50 +250,50 @@ union EntryInfo { } struct TreeEntry { - // The name of the entry in this directory. + /// The name of the entry in this directory. 1: string name; - // The type of the entry (file, link, exec, or sub-directory) + /// The type of the entry (file, link, exec, or sub-directory) 2: EntryType type; - // The info for the entry (file or sub-directory). + /// The info for the entry (file or sub-directory). 3: EntryInfo info; } struct FilePathInfo { - // The repo-root relative path. + /// The repo-root relative path. 1: string path; - // The type of the entry (file, link, exec) + /// The type of the entry (file, link, exec) 2: EntryType type; - // The info for the entry. + /// The info for the entry. 3: FileInfo info; } struct TreePathInfo { - // The repo-root relative path. + /// The repo-root relative path. 1: string path; - // The info for the entry. + /// The info for the entry. 2: TreeInfo info; } struct FileChunk { - // The offset within the file for this chunk. + /// The offset within the file for this chunk. 1: i64 offset; - // The total size of the file. + /// The total size of the file. 2: i64 file_size; - // The data for this chunk. + /// The data for this chunk. 3: binary data; } struct CommitCompareFile { 1: optional FilePathInfo base_file; 2: optional FilePathInfo other_file; - 3: CopyInfo copy_info; // Different than NONE only when commit is compared with parent + 3: CopyInfo copy_info; /// Different than NONE only when commit is compared with parent } struct CommitCompareTree { @@ -306,54 +306,54 @@ enum CommitCompareItem { TREES = 1, } -// The formats in which we can render the diff. -// Just one now, but we want to return more structured diffs in the future. +/// The formats in which we can render the diff. +/// Just one now, but we want to return more structured diffs in the future. enum DiffFormat { - // Raw diff (unified diff format with some of the "git diff" improvements) + /// Raw diff (unified diff format with some of the "git diff" improvements) RAW_DIFF = 0, } -// The formats in which we can render the diff. -// Just one now, but we want to return more structured diffs in the future. +/// The formats in which we can render the diff. +/// Just one now, but we want to return more structured diffs in the future. union Diff { 1: RawDiff raw_diff; } -// Raw diff (unified diff format with some of the "git diff" improvements). +/// Raw diff (unified diff format with some of the "git diff" improvements). struct RawDiff { - // Raw diff as bytes. + /// Raw diff as bytes. 1: optional binary raw_diff; - // One of the files is binary, raw diff contains just a placeholder. + /// One of the files is binary, raw diff contains just a placeholder. 2: bool is_binary; } -// Indicates whether the file was copied or moved +/// Indicates whether the file was copied or moved enum CopyInfo { - // File was modified, added or removed. + /// File was modified, added or removed. NONE = 0, - // File was moved. + /// File was moved. MOVE = 1, - // File was copied. + /// File was copied. COPY = 2, } enum BlameFormat { - // Use the BlameCompact format. + /// Use the BlameCompact format. COMPACT = 1, } enum BlameFormatOption { - // Applies to BlameCompact. Controls whether the blame includes the content - // of each line. + /// Applies to BlameCompact. Controls whether the blame includes the content + /// of each line. INCLUDE_CONTENTS = 1, - // Applies to BlameCompact. Controls whether the blame includes the titles - // (first line or 128 characters of the commit message) of the commits that - // introduced each line. + /// Applies to BlameCompact. Controls whether the blame includes the titles + /// (first line or 128 characters of the commit message) of the commits that + /// introduced each line. INCLUDE_TITLE = 2, - // Applies to BlameCompact. Controls whether the blame includes the messages - // of the commits that introduced each line. + /// Applies to BlameCompact. Controls whether the blame includes the messages + /// of the commits that introduced each line. INCLUDE_MESSAGE = 3, } @@ -361,13 +361,13 @@ union Blame { 2: BlameCompact blame_compact; } -// Compact blame format uses look-up tables for items that might be repeated -// across the file. Use the `_index` field in `BlameCompactLine` to index the -// corresponding list in the `BlameCompact` to get the item for each line. -// -// Some items might be missing, depending on the options selected in the -// request. In this case, the corresponding look-up table will also be -// omitted. +/// Compact blame format uses look-up tables for items that might be repeated +/// across the file. Use the `_index` field in `BlameCompactLine` to index the +/// corresponding list in the `BlameCompact` to get the item for each line. +/// +/// Some items might be missing, depending on the options selected in the +/// request. In this case, the corresponding look-up table will also be +/// omitted. struct BlameCompact { 1: list lines; 2: list> commit_ids; @@ -379,38 +379,38 @@ struct BlameCompact { } struct BlameCompactLine { - // The current line number of this line. + /// The current line number of this line. 1: i32 line; - // The content of this line. This is only provided if `format_options` - // included `INCLUDE_CONTENTS` in the request. + /// The content of this line. This is only provided if `format_options` + /// included `INCLUDE_CONTENTS` in the request. 2: optional string contents; - // The index in the look-up table of the commit ID that introduced the line. + /// The index in the look-up table of the commit ID that introduced the line. 3: i32 commit_id_index; - // The index in the look-up table of the path of the file when this line - // was introduced. + /// The index in the look-up table of the path of the file when this line + /// was introduced. 4: i32 path_index; - // The index in the look-up table of the author that introduced this line. + /// The index in the look-up table of the author that introduced this line. 5: i32 author_index; - // The index in the look-up table of the date when this line was introduced. + /// The index in the look-up table of the date when this line was introduced. 6: i32 date_index; - // The original line number when this line was introduced. + /// The original line number when this line was introduced. 7: i32 origin_line; - // The index in the look-up table of the title (first line or 128 characters - // of the commit message, whichever is shorter) of the commit that introduced - // this line. This is only provided if `format_options` included - // `INCLUDE_TITLE` in the request. + /// The index in the look-up table of the title (first line or 128 characters + /// of the commit message, whichever is shorter) of the commit that introduced + /// this line. This is only provided if `format_options` included + /// `INCLUDE_TITLE` in the request. 8: optional i32 title_index; - // The index in the look-up table of the message of the commit that - // introduced this line. This is only provided if `format_options` included - // `INCLUDE_MESSAGE` in the request. + /// The index in the look-up table of the message of the commit that + /// introduced this line. This is only provided if `format_options` included + /// `INCLUDE_MESSAGE` in the request. 9: optional i32 message_index; } @@ -425,124 +425,124 @@ union History { } struct PushrebaseRebasedCommit { - // The old commit id in the requested schemes. This uses - // old_identity_schemes if specified in the request. + /// The old commit id in the requested schemes. This uses + /// old_identity_schemes if specified in the request. 1: map old_ids; - // The new commit id in the requested schemes. + /// The new commit id in the requested schemes. 2: map new_ids; } struct PushrebaseOutcome { - // The new id for the rebased head. + /// The new id for the rebased head. 1: map head; - // List of mappings from old commit id to new commit id for the rebased - // commits. The identity schemes for the old ID is specified by the - // old_identity_schemes field in the request. + /// List of mappings from old commit id to new commit id for the rebased + /// commits. The identity schemes for the old ID is specified by the + /// old_identity_schemes field in the request. 2: list rebased_commits; } -// Method parameters structures +/// Method parameters structures struct ListReposParams { } struct RepoResolveBookmarkParams { - // The bookmark name to look up. + /// The bookmark name to look up. 1: string bookmark_name; - // Commit identity schemes to return. + /// Commit identity schemes to return. 2: set identity_schemes; } struct RepoResolveCommitPrefixParams { - // The commit hash prefix to look up. + /// The commit hash prefix to look up. 1: string prefix; - // Identity scheme of the given prefix. + /// Identity scheme of the given prefix. 2: CommitIdentityScheme prefix_scheme; - // Commit identity schemes to return. + /// Commit identity schemes to return. 3: set identity_schemes; } const i64 REPO_LIST_BOOKMARKS_MAX_LIMIT = 10000; struct RepoListBookmarksParams { - // If true, include scratch bookmarks. To list scratch bookmarks, you - // must provide a non-empty prefix and a limit. + /// If true, include scratch bookmarks. To list scratch bookmarks, you + /// must provide a non-empty prefix and a limit. 1: bool include_scratch; - // Prefix to match when listing bookmarks. + /// Prefix to match when listing bookmarks. 2: string bookmark_prefix; - // Limit to the number of bookmarks that may match. + /// Limit to the number of bookmarks that may match. 3: i64 limit; - // Return bookmarks after this name, to be used for paging. + /// Return bookmarks after this name, to be used for paging. 4: optional string after; - // Commit identity schemes to return. + /// Commit identity schemes to return. 5: set identity_schemes; } const i64 REPO_STACK_INFO_MAX_LIMIT = 10000; struct RepoStackInfoParams { - // Commit identity schemes to return. + /// Commit identity schemes to return. 1: set identity_schemes; - // List of heads to generate stack for. + /// List of heads to generate stack for. 2: list heads; - // Limits the number of draft changesets in the reponse, can be set up to - // REPO_STACK_INFO_MAX_LIMIT. + /// Limits the number of draft changesets in the reponse, can be set up to + /// REPO_STACK_INFO_MAX_LIMIT. 3: i64 limit; } enum RepoCreateCommitParamsFileType { - // Normal file + /// Normal file FILE = 1, - // Executable file + /// Executable file EXEC = 2, - // Symbolic link + /// Symbolic link LINK = 3, } union RepoCreateCommitParamsFileContent { - // Create the file using the provided data. + /// Create the file using the provided data. 1: binary data; - // Create the file using a pre-existing file specified by id. + /// Create the file using a pre-existing file specified by id. 2: binary id; - // Create the file using a pre-existing file specified by content SHA-1. + /// Create the file using a pre-existing file specified by content SHA-1. 3: binary content_sha1; - // Create the file using a pre-existing file specified by content SHA-256. + /// Create the file using a pre-existing file specified by content SHA-256. 4: binary content_sha256; } struct RepoCreateCommitParamsFileCopyInfo { - // Path the file was copied from. + /// Path the file was copied from. 1: string path; - // Index (in the list of the commit's parents) of the parent it was - // copied from. + /// Index (in the list of the commit's parents) of the parent it was + /// copied from. 2: i32 parent_index; } struct RepoCreateCommitParamsFileChanged { - // The new type of the file. + /// The new type of the file. 1: RepoCreateCommitParamsFileType type; - // The new content of the file. + /// The new content of the file. 2: RepoCreateCommitParamsFileContent content; - // The file was copied from another file. + /// The file was copied from another file. 3: optional RepoCreateCommitParamsFileCopyInfo copy_info; } @@ -550,133 +550,133 @@ struct RepoCreateCommitParamsFileDeleted { } union RepoCreateCommitParamsChange { - // The file was created or changed. + /// The file was created or changed. 1: RepoCreateCommitParamsFileChanged changed; - // The file was deleted. + /// The file was deleted. 2: RepoCreateCommitParamsFileDeleted deleted; } struct RepoCreateCommitParamsCommitInfo { - // The commit message. + /// The commit message. 1: string message; - // The date the commit was authored. If omitted, the server will use the - // current time in its default timezone. + /// The date the commit was authored. If omitted, the server will use the + /// current time in its default timezone. 2: optional DateTime date; - // The author of the commit. + /// The author of the commit. 3: string author; - // Extra metadata about the commit. + /// Extra metadata about the commit. 4: map extra; } struct RepoCreateCommitParams { - // The info for the new commit. + /// The info for the new commit. 1: RepoCreateCommitParamsCommitInfo info; - // The parents of the commit. + /// The parents of the commit. 2: list parents; - // A mapping from path to the change that is made at that path. + /// A mapping from path to the change that is made at that path. 3: map changes; - // Commit identity schemes to return. + /// Commit identity schemes to return. 4: set identity_schemes; - // Service identity to use for this commit creation. + /// Service identity to use for this commit creation. 5: optional string service_identity; } struct RepoCreateBookmarkParams { - // The name of the bookmark to move. + /// The name of the bookmark to move. 1: string bookmark; - // The target commit for the bookmark. + /// The target commit for the bookmark. 2: CommitId target; - // The pushvars to use when creating the bookmark. + /// The pushvars to use when creating the bookmark. 4: optional map pushvars; - // Service identity to use for this bookmark move. + /// Service identity to use for this bookmark move. 3: optional string service_identity; } struct RepoMoveBookmarkParams { - // The name of the bookmark to move. + /// The name of the bookmark to move. 1: string bookmark; - // The new target commit for the bookmark. + /// The new target commit for the bookmark. 2: CommitId target; - // The old bookmark target. If provided, only move the bookmark if it - // points at this commit. + /// The old bookmark target. If provided, only move the bookmark if it + /// points at this commit. 5: optional CommitId old_target; - // Whether non-fast-forward moves are allowed (a.k.a. force move). - // - // By default, non-fast-forward moves are prevented. Set this to `true` if - // you wish to allow a non-fast-forward move for the bookmark. - // - // Note: some bookmarks may be prevented from all non-fast-forward moves in - // the repository configuration. This flag will *not* override that - // configuration. + /// Whether non-fast-forward moves are allowed (a.k.a. force move). + /// + /// By default, non-fast-forward moves are prevented. Set this to `true` if + /// you wish to allow a non-fast-forward move for the bookmark. + /// + /// Note: some bookmarks may be prevented from all non-fast-forward moves in + /// the repository configuration. This flag will *not* override that + /// configuration. 3: bool allow_non_fast_forward_move; - // The pushvars to use when moving the bookmark. + /// The pushvars to use when moving the bookmark. 6: optional map pushvars; - // Service identity to use for this bookmark move. + /// Service identity to use for this bookmark move. 4: optional string service_identity; } struct RepoDeleteBookmarkParams { - // The name of the bookmark to move. + /// The name of the bookmark to move. 1: string bookmark; - // The old bookmark target. If provided, only delete the bookmark if it - // points at this commit. + /// The old bookmark target. If provided, only delete the bookmark if it + /// points at this commit. 2: optional CommitId old_target; - // The pushvars to use when deleting the bookmark. + /// The pushvars to use when deleting the bookmark. 4: optional map pushvars; - // Service identity to use for this bookmark move. + /// Service identity to use for this bookmark move. 3: optional string service_identity; } struct RepoLandStackParams { - // The name of the bookmark to land to. + /// The name of the bookmark to land to. 1: string bookmark; - // The head commit of the stack that is to be landed. + /// The head commit of the stack that is to be landed. 2: CommitId head; - // The parent of the bottom of the stack that is to be landed. This must - // match the merge base of the head commit with respect to the current - // bookmark location. + /// The parent of the bottom of the stack that is to be landed. This must + /// match the merge base of the head commit with respect to the current + /// bookmark location. 3: CommitId base; - // The set of commit identity schemes to return in the response. + /// The set of commit identity schemes to return in the response. 4: set identity_schemes; - // The commit identity schemes to use for the old commit ID of the - // pushrebased commits in the response. This can be used to prevent - // derivation of alternative commit formats for the old commits where the - // caller does not care about them. If not specified, then - // identity_schemes is used instead. + /// The commit identity schemes to use for the old commit ID of the + /// pushrebased commits in the response. This can be used to prevent + /// derivation of alternative commit formats for the old commits where the + /// caller does not care about them. If not specified, then + /// identity_schemes is used instead. 5: optional set old_identity_schemes; - // The pushvars to use when landing the stack. + /// The pushvars to use when landing the stack. 7: optional map pushvars; - // Service identity to use for the bookmark move. + /// Service identity to use for the bookmark move. 6: optional string service_identity; } struct CommitLookupParams { - // Commit identity schemes to return. + /// Commit identity schemes to return. 1: set identity_schemes; } @@ -684,12 +684,12 @@ struct CommitLookupPushrebaseHistoryParams { } struct CommitInfoParams { - // Commit identity schemes to return. + /// Commit identity schemes to return. 1: set identity_schemes; } struct CommitIsAncestorOfParams { - // Other commit to check if this commit is an ancestor of. + /// Other commit to check if this commit is an ancestor of. 1: CommitId other_commit_id; } @@ -699,108 +699,108 @@ struct CommitCommonBaseWithParams { } struct CommitCompareParams { - // Commit to compare with. By default it's the commit's first parent. + /// Commit to compare with. By default it's the commit's first parent. 1: optional CommitId other_commit_id; - // Shows copies as just file adds, and renames as adds and dels. + /// Shows copies as just file adds, and renames as adds and dels. 2: bool skip_copies_renames = false; - // Commit identity schemes to return. + /// Commit identity schemes to return. 3: set identity_schemes; - // Restrict the comparison to the given paths and their descendants + /// Restrict the comparison to the given paths and their descendants 4: optional list paths; - // What to compare (default is FILES) + /// What to compare (default is FILES) 5: set compare_items; } struct CommitFileDiffsParamsPathPair { - // Missing base path shows file as removed. + /// Missing base path shows file as removed. 1: optional Path base_path; - // Missing other path shows file as added. + /// Missing other path shows file as added. 2: optional Path other_path; - // Whether to render the diff as file move or copy - // (this method doesn't compute copy information) + /// Whether to render the diff as file move or copy + /// (this method doesn't compute copy information) 3: CopyInfo copy_info; - // If this option is set than instead of returning a real diff a placeholder - // diff like `Binary files ... differs` is returned. This option might be - // useful to display diff for very large files (i.e. files that are above - // COMMIT_FILE_DIFFS_SIZE_LIMIT). + /// If this option is set than instead of returning a real diff a placeholder + /// diff like `Binary files ... differs` is returned. This option might be + /// useful to display diff for very large files (i.e. files that are above + /// COMMIT_FILE_DIFFS_SIZE_LIMIT). 4: optional bool generate_placeholder_diff; } -const i64 COMMIT_FILE_DIFFS_SIZE_LIMIT = 0x4000000; // 64MiB +const i64 COMMIT_FILE_DIFFS_SIZE_LIMIT = 0x4000000; /// 64MiB const i64 COMMIT_FILE_DIFFS_PATH_COUNT_LIMIT = 1000; struct CommitFileDiffsParams { - // The commit to diff against. + /// The commit to diff against. 1: CommitId other_commit_id; - // List of paths to diffs: in a single request - // * at most COMMIT_FILE_DIFFS_PATH_COUNT_LIMIT paths can be requested - // * the total size of diffed files must be less than COMMIT_FILE_DIFFS_SIZE_LIMIT - // unless `generate_placeholder_diff` is set in - // CommitFileDiffsParamsPathPair + /// List of paths to diffs: in a single request + /// * at most COMMIT_FILE_DIFFS_PATH_COUNT_LIMIT paths can be requested + /// * the total size of diffed files must be less than COMMIT_FILE_DIFFS_SIZE_LIMIT + /// unless `generate_placeholder_diff` is set in + /// CommitFileDiffsParamsPathPair 2: list paths; 3: DiffFormat format; - // Number of lines of unified context around differences (default: 3) + /// Number of lines of unified context around differences (default: 3) 4: i64 context = 3; } const i64 COMMIT_FIND_FILES_MAX_LIMIT = 100000; struct CommitFindFilesParams { - // Limit to the number of tree entries listed. If the request returns - // the limit, a subsequent call with 'after' set to the last path in the - // response is necessary to find the remaining files. + /// Limit to the number of tree entries listed. If the request returns + /// the limit, a subsequent call with 'after' set to the last path in the + /// response is necessary to find the remaining files. 1: i64 limit; - // Start listing files after this path, to be used for paging (not - // implemented yet). - // 2: optional string after, + /// Start listing files after this path, to be used for paging (not + /// implemented yet). + /// 2: optional string after, - // Return entries that have these basenames. + /// Return entries that have these basenames. 3: optional list basenames; - // Return entries that have these path prefixes. + /// Return entries that have these path prefixes. 4: optional list prefixes; } struct CommitHistoryParams { - // Return history in the given format. + /// Return history in the given format. 1: HistoryFormat format; - // Number of commits to return in the history. + /// Number of commits to return in the history. 2: i32 limit; - // Number of commits to skip before listing the history. + /// Number of commits to skip before listing the history. 3: i32 skip; - // Show commits created only before the given timestamp. - // Timestamp must be greater than 0. + /// Show commits created only before the given timestamp. + /// Timestamp must be greater than 0. 4: optional i64 before_timestamp; - // Show commits created only after the given timestamp. - // Timestamp must be greater than 0. + /// Show commits created only after the given timestamp. + /// Timestamp must be greater than 0. 5: optional i64 after_timestamp; - // Commit identity schemes to return in the commit information. + /// Commit identity schemes to return in the commit information. 6: set identity_schemes; - // Include only commits that are descendants of the given commit (including - // the commit itself) + /// Include only commits that are descendants of the given commit (including + /// the commit itself) 7: optional CommitId descendants_of; - // Exclude commit and all of its ancestor from results. + /// Exclude commit and all of its ancestor from results. 8: optional CommitId exclude_changeset_and_ancestors; } const i64 COMMIT_LIST_DESCENDANT_BOOKMARKS_MAX_LIMIT = 10000; struct CommitListDescendantBookmarksParams { - // If true, include scratch bookmarks. To list scratch bookmarks, you - // must provide a non-empty prefix and a limit. + /// If true, include scratch bookmarks. To list scratch bookmarks, you + /// must provide a non-empty prefix and a limit. 1: bool include_scratch; - // Prefix to match when listing bookmarks. + /// Prefix to match when listing bookmarks. 2: string bookmark_prefix; - // Limit to the number of bookmarks that may match. + /// Limit to the number of bookmarks that may match. 3: i64 limit; - // Return bookmarks after this name, to be used for paging. + /// Return bookmarks after this name, to be used for paging. 4: optional string after; - // Commit identity schemes to return. + /// Commit identity schemes to return. 5: set identity_schemes; } @@ -813,41 +813,41 @@ struct CommitPathInfoParams { const i64 TREE_LIST_MAX_LIMIT = 10000; struct CommitPathBlameParams { - // Which format to use in the response. + /// Which format to use in the response. 1: BlameFormat format; - // Commit identity schemes to return. + /// Commit identity schemes to return. 3: set identity_schemes; - // Options to customize the blame format. The interpretation of these is - // up to the blame format. - // - // If not specified, defaults to {INCLUDE_CONTENT}. + /// Options to customize the blame format. The interpretation of these is + /// up to the blame format. + /// + /// If not specified, defaults to {INCLUDE_CONTENT}. 4: optional set format_options; } struct CommitPathHistoryParams { - // Return history in the given format. + /// Return history in the given format. 1: HistoryFormat format; - // Number of commits to return in the history. + /// Number of commits to return in the history. 2: i32 limit; - // Number of commits to skip before listing the history. + /// Number of commits to skip before listing the history. 3: i32 skip; - // Show commits created only before the given timestamp. - // Timestamp must be greater than 0. + /// Show commits created only before the given timestamp. + /// Timestamp must be greater than 0. 4: optional i64 before_timestamp; - // Show commits created only after the given timestamp. - // Timestamp must be greater than 0. + /// Show commits created only after the given timestamp. + /// Timestamp must be greater than 0. 5: optional i64 after_timestamp; - // Commit identity schemes to return in the commit information. + /// Commit identity schemes to return in the commit information. 6: set identity_schemes; - // Tracks history of a path even if it was deleted and then reintroduced - // This is more expensive and generally discouraged to use. + /// Tracks history of a path even if it was deleted and then reintroduced + /// This is more expensive and generally discouraged to use. 7: bool follow_history_across_deletions; - // Include only commits that are descendants of the given commit (including - // the commit itself) + /// Include only commits that are descendants of the given commit (including + /// the commit itself) 8: optional CommitId descendants_of; - // Exclude commit and all of its ancestor from results. + /// Exclude commit and all of its ancestor from results. 9: optional CommitId exclude_changeset_and_ancestors; } @@ -855,10 +855,10 @@ struct TreeExistsParams { } struct TreeListParams { - // Start listing at this offset in the tree. + /// Start listing at this offset in the tree. 1: i64 offset; - // Limit to the number of tree entries listed. + /// Limit to the number of tree entries listed. 2: i64 limit; } @@ -868,20 +868,20 @@ struct FileExistsParams { struct FileInfoParams { } -const i64 FILE_CONTENT_CHUNK_SIZE_LIMIT = 0x1000000; // 16MiB +const i64 FILE_CONTENT_CHUNK_SIZE_LIMIT = 0x1000000; /// 16MiB -// Recommended chunk size for file_content_chunk requests. This is just a -// suggestion - the client may use any chunk size up to the limit and the -// server will re-chunk as necessary. -const i64 FILE_CONTENT_CHUNK_RECOMMENDED_SIZE = 0x3FFC00; // 4MiB - 1KiB +/// Recommended chunk size for file_content_chunk requests. This is just a +/// suggestion - the client may use any chunk size up to the limit and the +/// server will re-chunk as necessary. +const i64 FILE_CONTENT_CHUNK_RECOMMENDED_SIZE = 0x3FFC00; /// 4MiB - 1KiB struct FileContentChunkParams { - // The offset within the file to fetch. + /// The offset within the file to fetch. 1: i64 offset; - // The requested chunk size. If the requested size from this offset goes - // past the end of the file, then only the bytes up to the end of the - // file are returned. + /// The requested chunk size. If the requested size from this offset goes + /// past the end of the file, then only the bytes up to the end of the + /// file are returned. 2: i64 size; } @@ -889,36 +889,36 @@ struct FileContentStreamParams { } struct FileDiffParams { - // The ID of the other file, obtained from a previous response. + /// The ID of the other file, obtained from a previous response. 1: binary other_file_id; - // Diff format to return, + /// Diff format to return, 3: DiffFormat format; - // Number of lines of unified context around differences (default: 3) + /// Number of lines of unified context around differences (default: 3) 4: i64 context = 3; } union CandidateSelectionHint { - // Select an ancestor of a given bookmark + /// Select an ancestor of a given bookmark 1: string bookmark_ancestor; - // Select a descendant of a given bookmark + /// Select a descendant of a given bookmark 2: string bookmark_descendant; - // Select an ancestor of a given commit + /// Select an ancestor of a given commit 3: CommitId commit_ancestor; - // Select a descendant of a given commit + /// Select a descendant of a given commit 4: CommitId commit_descendant; - // Select a given commit from a list of candidates + /// Select a given commit from a list of candidates 5: CommitId exact; } struct CommitLookupXRepoParams { - // The other repo to look in + /// The other repo to look in 1: RepoSpecifier other_repo; - // Commit identity schemes to return. + /// Commit identity schemes to return. 2: set identity_schemes; - // Candidate selection hint for resolving plural - // mapping situations + /// Candidate selection hint for resolving plural + /// mapping situations 3: optional CandidateSelectionHint candidate_selection_hint; } @@ -926,150 +926,150 @@ struct RepoListHgManifestParams { 1: binary hg_manifest_id; } -// Polling tokens for async megarepo methods +/// Polling tokens for async megarepo methods struct MegarepoChangeConfigToken { - // A target this token relates to + /// A target this token relates to 1: megarepo_configs.Target target; - // An actual token payload + /// An actual token payload 2: i64 id; } struct MegarepoSyncChangesetToken { - // A target this token relates to + /// A target this token relates to 1: megarepo_configs.Target target; - // An actual token payload + /// An actual token payload 2: i64 id; } struct MegarepoRemergeSourceToken { - // A target this token relates to + /// A target this token relates to 1: megarepo_configs.Target target; - // An actual token payload + /// An actual token payload 2: i64 id; } struct MegarepoAddTargetToken { - // A target this token relates to + /// A target this token relates to 1: megarepo_configs.Target target; - // An actual token payload + /// An actual token payload 2: i64 id; } struct MegarepoAddBranchingTargetToken { - // A target this token relates to + /// A target this token relates to 1: megarepo_configs.Target target; - // An actual token payload + /// An actual token payload 2: i64 id; } -// Params for the megarepo_add_sync_target_config method +/// Params for the megarepo_add_sync_target_config method struct MegarepoAddConfigParams { - // New config to be added to the config library - // the config *must* refer to an existing target - // Config's version *must* be different from - // any previously used config version + /// New config to be added to the config library + /// the config *must* refer to an existing target + /// Config's version *must* be different from + /// any previously used config version 1: megarepo_configs.SyncTargetConfig new_config; } -// Params for megarepo_add_sync_target method +/// Params for megarepo_add_sync_target method struct MegarepoAddTargetParams { - // Initial config to be used on the new target - // The config *must* refer to the not-yet-existing target - // which will be recorded as new target - // Config's version must be different from - // any previously used config version + /// Initial config to be used on the new target + /// The config *must* refer to the not-yet-existing target + /// which will be recorded as new target + /// Config's version must be different from + /// any previously used config version 1: megarepo_configs.SyncTargetConfig config_with_new_target; - // Initial changesets to merge for each of the - // sources in the `config_with_new_target`. - // While each source provides a revision to - // be followed in the future, at the moment of - // the initial target creation, it may be needed - // to merge an ancestor of said revision. That is - // why this field exists. Each source's changeset - // MUST be an ancestor of the source revision if the - // source revision is a bookmark, and it MUST be equal - // to the source revision if it is a changeset itself - // Each source name MUST be present in this map. + /// Initial changesets to merge for each of the + /// sources in the `config_with_new_target`. + /// While each source provides a revision to + /// be followed in the future, at the moment of + /// the initial target creation, it may be needed + /// to merge an ancestor of said revision. That is + /// why this field exists. Each source's changeset + /// MUST be an ancestor of the source revision if the + /// source revision is a bookmark, and it MUST be equal + /// to the source revision if it is a changeset itself + /// Each source name MUST be present in this map. 2: map changesets_to_merge; - // A message to be used in the commit description - // If not provided, service will generate commit description + /// A message to be used in the commit description + /// If not provided, service will generate commit description 3: optional string message; } -// Params for megarepo_add_sync_target method +/// Params for megarepo_add_sync_target method struct MegarepoAddBranchingTargetParams { - // A new target to be created + /// A new target to be created 1: megarepo_configs.Target target; - // The specified commit will be used as parent of the first commit in the - // newly created target. The megarepo config used to create the branching - // point will be used as the base for the new target config. + /// The specified commit will be used as parent of the first commit in the + /// newly created target. The megarepo config used to create the branching + /// point will be used as the base for the new target config. 2: megarepo_configs.ChangesetId branching_point; - // The specified source target to use as the source of config for this - // new target. This call will verify that branching_point is a valid - // commit to use with that source target + /// The specified source target to use as the source of config for this + /// new target. This call will verify that branching_point is a valid + /// commit to use with that source target 3: megarepo_configs.Target source_target; } -// Params for megarepo_change_target_config method +/// Params for megarepo_change_target_config method struct MegarepoChangeTargetConfigParams { - // A target for which to change the version + /// A target for which to change the version 1: megarepo_configs.Target target; - // New config version to be used for the target above - // This version *must* refer to the `target` + /// New config version to be used for the target above + /// This version *must* refer to the `target` 2: megarepo_configs.SyncConfigVersion new_version; - // Current location of the `target`'s bookmark. - // This argument exists to prevent race conditions + /// Current location of the `target`'s bookmark. + /// This argument exists to prevent race conditions 3: megarepo_configs.ChangesetId target_location; - // Initial changesets to merge for each of the - // sources in the `target`. Similar to `changesets_to_merge` - // in the `MegarepoAddTargetParams` struct, see docstring - // there + /// Initial changesets to merge for each of the + /// sources in the `target`. Similar to `changesets_to_merge` + /// in the `MegarepoAddTargetParams` struct, see docstring + /// there 4: map changesets_to_merge; - // A message to be used in the commit description - // If not provided, service will generate commit description + /// A message to be used in the commit description + /// If not provided, service will generate commit description 5: optional string message; } -// Params for megarepo_sync_changeset method +/// Params for megarepo_sync_changeset method struct MegarepoSyncChangesetParams { - // Source from which to sync the changeset + /// Source from which to sync the changeset 1: string source_name; - // Target into which to sync the changeset + /// Target into which to sync the changeset 2: megarepo_configs.Target target; - // This operation will sync all not-yet synced - // changesets up to and including `cs_id` from - // `source` into `target` + /// This operation will sync all not-yet synced + /// changesets up to and including `cs_id` from + /// `source` into `target` 3: megarepo_configs.ChangesetId cs_id; - // Current location of the `target`'s bookmark. - // This argument exists to prevent race conditions + /// Current location of the `target`'s bookmark. + /// This argument exists to prevent race conditions 4: megarepo_configs.ChangesetId target_location; } -// Params for megarepo_re_merge_source method +/// Params for megarepo_re_merge_source method struct MegarepoRemergeSourceParams { - // Source which needs remerging + /// Source which needs remerging 1: string source_name; - // Target into which to remerge the source + /// Target into which to remerge the source 2: megarepo_configs.Target target; - // Remerge source at `cs_id` and mark `cs_id` - // as the last synced changeset form this source - // Note: this does not do any ancestry checks - // with previous changesets synced form the same - // source + /// Remerge source at `cs_id` and mark `cs_id` + /// as the last synced changeset form this source + /// Note: this does not do any ancestry checks + /// with previous changesets synced form the same + /// source 3: megarepo_configs.ChangesetId cs_id; - // Current location of the `target`'s bookmark. - // This argument exists to prevent race conditions + /// Current location of the `target`'s bookmark. + /// This argument exists to prevent race conditions 4: megarepo_configs.ChangesetId target_location; - // A message to be used in the commit description - // If not provided, service will generate commit description + /// A message to be used in the commit description + /// If not provided, service will generate commit description 5: optional string message; } -// Method response structures +/// Method response structures struct RepoResolveBookmarkResponse { - // Whether the bookmark exists. + /// Whether the bookmark exists. 1: bool exists; - // The bookmarked commit's IDs in the requested schemes (if available). + /// The bookmarked commit's IDs in the requested schemes (if available). 2: optional map ids; } @@ -1082,37 +1082,37 @@ enum RepoResolveCommitPrefixResponseType { struct RepoResolveCommitPrefixResponse { 1: RepoResolveCommitPrefixResponseType resolved_type; - // The resolve commit IDs in the requested schemes (if type == RESOLVED) + /// The resolve commit IDs in the requested schemes (if type == RESOLVED) 2: optional map ids; } struct RepoListBookmarksResponse { - // A map from bookmark name to the bookmarked commit's IDs in the - // requested schemes (if available). + /// A map from bookmark name to the bookmarked commit's IDs in the + /// requested schemes (if available). 1: map> bookmarks; - // If set, there are potentially more bookmarks. Provide this - // bookmark name as the `after` parameter in a new request to - // continue finding them. + /// If set, there are potentially more bookmarks. Provide this + /// bookmark name as the `after` parameter in a new request to + /// continue finding them. 2: optional string continue_after; } struct RepoStackInfoResponse { - // Draft commits in topological order. + /// Draft commits in topological order. 1: list draft_commits; - // Public roots in topological order. + /// Public roots in topological order. 2: list public_parents; - // List of commits that weren't considered yet because the limit was - // reached. To find more, call repo_stack_info again with this list as the - // list of heads. Note that shared ancestry may result in duplicate - // commits in subsequent calls. + /// List of commits that weren't considered yet because the limit was + /// reached. To find more, call repo_stack_info again with this list as the + /// list of heads. Note that shared ancestry may result in duplicate + /// commits in subsequent calls. 3: list> leftover_heads; } struct RepoCreateCommitResponse { - // The IDs of the created commit. + /// The IDs of the created commit. 1: map ids; } @@ -1130,14 +1130,14 @@ struct RepoLandStackResponse { } struct CommitCompareResponse { - // List of the files that are different between commits with their metadata - // Can be used for subsequent `commit_path_diff` calls for file-level diffs. - // Only populated if FILES was specified. + /// List of the files that are different between commits with their metadata + /// Can be used for subsequent `commit_path_diff` calls for file-level diffs. + /// Only populated if FILES was specified. 1: list diff_files; - // Commit that was used for comparison + /// Commit that was used for comparison 2: map other_commit_ids; - // List of the dirs that are different between commits with their metadata - // Only populated if TREES was specified. + /// List of the dirs that are different between commits with their metadata + /// Only populated if TREES was specified. 3: list diff_trees; } @@ -1152,21 +1152,21 @@ struct CommitFileDiffsResponse { } struct CommitLookupResponse { - // Whether the commit exists. + /// Whether the commit exists. 1: bool exists; - // The commit's IDs in the requested schemes (if available). + /// The commit's IDs in the requested schemes (if available). 2: optional map ids; } struct CommitLookupPushrebaseHistoryResponse { 1: list history; - // Always equals to the last element of history + /// Always equals to the last element of history 2: CommitSpecifier origin; } struct CommitFindFilesResponse { - // The files that match. + /// The files that match. 1: list files; } @@ -1175,35 +1175,35 @@ struct CommitHistoryResponse { } struct CommitListDescendantBookmarksResponse { - // The map of bookmarks that are descendants of this bookmark and - // the commit they refer to. + /// The map of bookmarks that are descendants of this bookmark and + /// the commit they refer to. 1: map> bookmarks; - // If set, there are potentially more bookmarks. Provide this - // bookmark name as the `after` parameter in a new request to - // continue finding them. + /// If set, there are potentially more bookmarks. Provide this + /// bookmark name as the `after` parameter in a new request to + /// continue finding them. 2: optional string continue_after; } struct CommitPathExistsResponse { - // Whether anything exists at this path. + /// Whether anything exists at this path. 1: bool exists; - // Whether a file exists at this path. + /// Whether a file exists at this path. 2: bool file_exists; - // Whether a tree (directory) exists at this path. + /// Whether a tree (directory) exists at this path. 3: bool tree_exists; } struct CommitPathInfoResponse { - // Whether an item exists at this path. + /// Whether an item exists at this path. 1: bool exists; - // The type of the item at this path (file, link, exec, or directory). + /// The type of the item at this path (file, link, exec, or directory). 2: optional EntryType type; - // The info for the item. + /// The info for the item. 3: optional EntryInfo info; } @@ -1220,37 +1220,37 @@ struct CommitPathHistoryResponse { } struct TreeListResponse { - // The directory entries in this directory, at the offset requested, - // limited by the limit requested. + /// The directory entries in this directory, at the offset requested, + /// limited by the limit requested. 1: list entries; - // The total number of entries in this directory. If this is greater - // than the requested limit, then more requests to get the rest of the - // list will be required. + /// The total number of entries in this directory. If this is greater + /// than the requested limit, then more requests to get the rest of the + /// list will be required. 2: i64 count; } struct FileDiffResponse { - // The differences between the two files. + /// The differences between the two files. 1: Diff diff; } struct HgManifestFileInfo { - // The id of the file contents that can be used in subsequent look-ups. + /// The id of the file contents that can be used in subsequent look-ups. 1: binary hg_filenode_id; - // The size of the file, or the length of the link target path for links. + /// The size of the file, or the length of the link target path for links. 2: i64 file_size; - // The content sha1 of the file. + /// The content sha1 of the file. 3: binary content_sha1; - // The content sha256 of the file. + /// The content sha256 of the file. 4: binary content_sha256; } struct HgManifestTreeInfo { - // The manifest id of the tree that can be used in subsequent look-ups. + /// The manifest id of the tree that can be used in subsequent look-ups. 1: binary hg_manifest_id; } @@ -1260,13 +1260,13 @@ union HgManifestEntryInfo { } struct HgManifestEntry { - // The name of the entry in this directory. + /// The name of the entry in this directory. 1: string name; - // The type of the entry (file, link, exec, or sub-directory) + /// The type of the entry (file, link, exec, or sub-directory) 2: EntryType type; - // The info for the entry (file or sub-directory). + /// The info for the entry (file or sub-directory). 3: HgManifestEntryInfo info; } @@ -1278,8 +1278,8 @@ struct MegarepoAddConfigResponse { } struct MegarepoAddTargetResponse { - // A new position of the target bookmark - // after the "sync changeset" operaton finished + /// A new position of the target bookmark + /// after the "sync changeset" operaton finished 1: megarepo_configs.ChangesetId cs_id; } @@ -1289,12 +1289,12 @@ union MegarepoAddTargetResult { } struct MegarepoAddTargetPollResponse { - // Maybe a response to an underlying call, if it is ready + /// Maybe a response to an underlying call, if it is ready 1: optional MegarepoAddTargetResult result; } struct MegarepoAddBranchingTargetResponse { - // A new position of the target bookmark + /// A new position of the target bookmark 1: megarepo_configs.ChangesetId cs_id; } @@ -1304,13 +1304,13 @@ union MegarepoAddBranchingTargetResult { } struct MegarepoAddBranchingTargetPollResponse { - // Maybe a response to an underlying call, if it is ready + /// Maybe a response to an underlying call, if it is ready 1: optional MegarepoAddBranchingTargetResult result; } struct MegarepoChangeTargetConfigResponse { - // A new position of the target bookmark - // after the "change config" operaton finished + /// A new position of the target bookmark + /// after the "change config" operaton finished 1: megarepo_configs.ChangesetId cs_id; } @@ -1320,13 +1320,13 @@ union MegarepoChangeTargetConfigResult { } struct MegarepoChangeTargetConfigPollResponse { - // Maybe a response to an underlying call, if it is ready + /// Maybe a response to an underlying call, if it is ready 1: optional MegarepoChangeTargetConfigResult result; } struct MegarepoSyncChangesetResponse { - // A new position of the target bookmark - // after the "sync changeset" operaton finished + /// A new position of the target bookmark + /// after the "sync changeset" operaton finished 1: megarepo_configs.ChangesetId cs_id; } @@ -1336,13 +1336,13 @@ union MegarepoSyncChangesetResult { } struct MegarepoSyncChangesetPollResponse { - // Maybe a response to an underlying call, if it is ready + /// Maybe a response to an underlying call, if it is ready 1: optional MegarepoSyncChangesetResult result; } struct MegarepoRemergeSourceResponse { - // A new position of the target bookmark - // after the "remerge source" operaton finished + /// A new position of the target bookmark + /// after the "remerge source" operaton finished 1: megarepo_configs.ChangesetId cs_id; } @@ -1352,11 +1352,11 @@ union MegarepoRemergeSourceResult { } struct MegarepoRemergeSourcePollResponse { - // Maybe a response to an underlying call, if it is ready + /// Maybe a response to an underlying call, if it is ready 1: optional MegarepoRemergeSourceResult result; } -// Exceptions +/// Exceptions enum RequestErrorKind { UNKNOWN = 0, @@ -1399,150 +1399,150 @@ union MegarepoAsynchronousRequestError { 2: InternalErrorStruct internal_error; } -// Service Definition +/// Service Definition service SourceControlService extends fb303.FacebookService { - // Global methods - // ============== + /// Global methods + /// ============== - // Get a list of all repositories. + /// Get a list of all repositories. list list_repos(1: ListReposParams params) throws ( 1: RequestError request_error, 2: InternalError internal_error, ); - // Repository methods - // ================== + /// Repository methods + /// ================== - // Resolve a bookmark. + /// Resolve a bookmark. RepoResolveBookmarkResponse repo_resolve_bookmark( 1: RepoSpecifier repo, 2: RepoResolveBookmarkParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Resolve commit by the given prefix + /// Resolve commit by the given prefix RepoResolveCommitPrefixResponse repo_resolve_commit_prefix( 1: RepoSpecifier repo, 2: RepoResolveCommitPrefixParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // List all bookmarks in the repo. + /// List all bookmarks in the repo. RepoListBookmarksResponse repo_list_bookmarks( 1: RepoSpecifier repo, 2: RepoListBookmarksParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Generate commit info for all the draft commits - // for the given set of heads.and public roots. + /// Generate commit info for all the draft commits + /// for the given set of heads.and public roots. RepoStackInfoResponse repo_stack_info( 1: RepoSpecifier repo, 2: RepoStackInfoParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Repository write methods - // ======================== + /// Repository write methods + /// ======================== - // Create a new commit. + /// Create a new commit. RepoCreateCommitResponse repo_create_commit( 1: RepoSpecifier repo, 2: RepoCreateCommitParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Create a bookmark. + /// Create a bookmark. RepoCreateBookmarkResponse repo_create_bookmark( 1: RepoSpecifier repo, 2: RepoCreateBookmarkParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Move a bookmark. + /// Move a bookmark. RepoMoveBookmarkResponse repo_move_bookmark( 1: RepoSpecifier repo, 2: RepoMoveBookmarkParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Delete a bookmark. + /// Delete a bookmark. RepoDeleteBookmarkResponse repo_delete_bookmark( 1: RepoSpecifier repo, 2: RepoDeleteBookmarkParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Land a stack of commits via pushrebase. + /// Land a stack of commits via pushrebase. RepoLandStackResponse repo_land_stack( 1: RepoSpecifier repo, 2: RepoLandStackParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Commit methods - // ============== + /// Commit methods + /// ============== - // Diff paths in commit against paths in other commits. - // NOTE: Works only on files, doesn't diff directories. - // NOTE2: There are limits on how many files you can diff at once: - // * at most COMMIT_DIFF_FILES_PATH_COUNT_LIMIT paths can be requested - // * the total size of diffed files must be less than - // COMMIT_DIFF_FILES_SIZE_LIMIT + /// Diff paths in commit against paths in other commits. + /// NOTE: Works only on files, doesn't diff directories. + /// NOTE2: There are limits on how many files you can diff at once: + /// * at most COMMIT_DIFF_FILES_PATH_COUNT_LIMIT paths can be requested + /// * the total size of diffed files must be less than + /// COMMIT_DIFF_FILES_SIZE_LIMIT CommitFileDiffsResponse commit_file_diffs( 1: CommitSpecifier commit, 2: CommitFileDiffsParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Look-up a commit to see if it exists and find alternative IDs. + /// Look-up a commit to see if it exists and find alternative IDs. CommitLookupResponse commit_lookup( 1: CommitSpecifier commit, 2: CommitLookupParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Look up commit history over Pushrebase mutations. It finishes on commit - // version that was originally pushed. Provided commit must be public. - // - // Currently attempts to traverse over commit sync and pushrebase mappings. - // Returns an error if there is ambiguity in any mapping but this is not - // expected to ever happen. - // - // Method may also theoretically return inaccurate results because of the - // way commit sync mapping currently works. "Inaccurate" means it may - // go in the wrong direction and return a commit that was a successor - // of the given one. This should be fixed soon. In the meantime you can - // consider using full history from the response if you are fine with a set - // of origin "candidates" rather than the exact one which may be incorrect. - // - // NOTE: returns commit specifiers with bonsai hashes. Use commit_lookup - // on specifiers to obtain hashes in needed schemes. + /// Look up commit history over Pushrebase mutations. It finishes on commit + /// version that was originally pushed. Provided commit must be public. + /// + /// Currently attempts to traverse over commit sync and pushrebase mappings. + /// Returns an error if there is ambiguity in any mapping but this is not + /// expected to ever happen. + /// + /// Method may also theoretically return inaccurate results because of the + /// way commit sync mapping currently works. "Inaccurate" means it may + /// go in the wrong direction and return a commit that was a successor + /// of the given one. This should be fixed soon. In the meantime you can + /// consider using full history from the response if you are fine with a set + /// of origin "candidates" rather than the exact one which may be incorrect. + /// + /// NOTE: returns commit specifiers with bonsai hashes. Use commit_lookup + /// on specifiers to obtain hashes in needed schemes. CommitLookupPushrebaseHistoryResponse commit_lookup_pushrebase_history( 1: CommitSpecifier commit, 2: CommitLookupPushrebaseHistoryParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Get commit info. + /// Get commit info. CommitInfo commit_info( 1: CommitSpecifier commit, 2: CommitInfoParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Check if this commit is an ancestor of some other commit. + /// Check if this commit is an ancestor of some other commit. bool commit_is_ancestor_of( 1: CommitSpecifier commit, 2: CommitIsAncestorOfParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Find the lowest common ancestor of two commits. - // - // In case of ambiguity (can happen with multiple merges of the same - // branches) returns the common ancestor with lowest hash out of those with - // highest generation number. + /// Find the lowest common ancestor of two commits. + /// + /// In case of ambiguity (can happen with multiple merges of the same + /// branches) returns the common ancestor with lowest hash out of those with + /// highest generation number. CommitLookupResponse commit_common_base_with( 1: CommitSpecifier commit, 2: CommitCommonBaseWithParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Compute differences between two commits. - // note: copy/move information included only when comparing with parent + /// Compute differences between two commits. + /// note: copy/move information included only when comparing with parent CommitCompareResponse commit_compare( 1: CommitSpecifier commit, 2: CommitCompareParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Find files within the commit that match criteria. + /// Find files within the commit that match criteria. CommitFindFilesResponse commit_find_files( 1: CommitSpecifier commit, 2: CommitFindFilesParams params, @@ -1558,22 +1558,22 @@ service SourceControlService extends fb303.FacebookService { 2: CommitListDescendantBookmarksParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // CommitPath methods - // ============== + /// CommitPath methods + /// ============== - // Determine whether a path exists and what type it is. + /// Determine whether a path exists and what type it is. CommitPathExistsResponse commit_path_exists( 1: CommitPathSpecifier commit_path, 2: CommitPathExistsParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Get information about a path in a commit. + /// Get information about a path in a commit. CommitPathInfoResponse commit_path_info( 1: CommitPathSpecifier commit_path, 2: CommitPathInfoParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Get information about multiple paths in a commit. + /// Get information about multiple paths in a commit. CommitMultiplePathInfoResponse commit_multiple_path_info( 1: CommitSpecifier commit, 2: CommitMultiplePathInfoParams params, @@ -1589,139 +1589,139 @@ service SourceControlService extends fb303.FacebookService { 2: CommitPathHistoryParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Tree Methods - // ============ + /// Tree Methods + /// ============ - // Determine whether a tree exists. + /// Determine whether a tree exists. bool tree_exists(1: TreeSpecifier file, 2: TreeExistsParams params) throws ( 1: RequestError request_error, 2: InternalError internal_error, ); - // List the contents of a directory. + /// List the contents of a directory. TreeListResponse tree_list( 1: TreeSpecifier tree, 2: TreeListParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // File Methods - // ============ + /// File Methods + /// ============ - // Determine whether a file exists. + /// Determine whether a file exists. bool file_exists(1: FileSpecifier file, 2: FileExistsParams params) throws ( 1: RequestError request_error, 2: InternalError internal_error, ); - // Get information about a file. + /// Get information about a file. FileInfo file_info(1: FileSpecifier file, 2: FileInfoParams params) throws ( 1: RequestError request_error, 2: InternalError internal_error, ); - // Get a chunk of a file's content. + /// Get a chunk of a file's content. FileChunk file_content_chunk( 1: FileSpecifier file, 2: FileContentChunkParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Compare a file with another file. + /// Compare a file with another file. FileDiffResponse file_diff( 1: FileSpecifier file, 2: FileDiffParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Old-style Cross-Repo Methods (used for ovrsource merge into fbsource) - // ============================ + /// Old-style Cross-Repo Methods (used for ovrsource merge into fbsource) + /// ============================ - // Look-up a commit to find its identity (if any) in another repo + /// Look-up a commit to find its identity (if any) in another repo CommitLookupResponse commit_lookup_xrepo( 1: CommitSpecifier commit, 2: CommitLookupXRepoParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Megarepo Service Methods - // ======================== + /// Megarepo Service Methods + /// ======================== - // Add a new unused config version to the library of versions + /// Add a new unused config version to the library of versions MegarepoAddConfigResponse megarepo_add_sync_target_config( 1: MegarepoAddConfigParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Add a new target to the list of known targets and set its - // initial SyncTargetConfig value + /// Add a new target to the list of known targets and set its + /// initial SyncTargetConfig value MegarepoAddTargetToken megarepo_add_sync_target( 1: MegarepoAddTargetParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - /// Poll the execution of megarepo_add_sync_target request + //// Poll the execution of megarepo_add_sync_target request MegarepoAddTargetPollResponse megarepo_add_sync_target_poll( 1: MegarepoAddTargetToken token, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Add a new target that branches off existing target. + /// Add a new target that branches off existing target. MegarepoAddBranchingTargetToken megarepo_add_branching_sync_target( 1: MegarepoAddBranchingTargetParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - /// Poll the execution of megarepo_add_sync_target request + //// Poll the execution of megarepo_add_sync_target request MegarepoAddBranchingTargetPollResponse megarepo_add_branching_sync_target_poll( 1: MegarepoAddBranchingTargetToken token, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Set target's version to a new value while applying necessary transformations - // These transformations may include: - // - deletions of old mappings of sources that need to be re-merged - // - transformation-applying changesets on sources - // - re-merges of sources - // Returns a new position of the target bookmark - // Note: may advance the bookmark by >1 commit + /// Set target's version to a new value while applying necessary transformations + /// These transformations may include: + /// - deletions of old mappings of sources that need to be re-merged + /// - transformation-applying changesets on sources + /// - re-merges of sources + /// Returns a new position of the target bookmark + /// Note: may advance the bookmark by >1 commit MegarepoChangeConfigToken megarepo_change_target_config( 1: MegarepoChangeTargetConfigParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Poll the execution of change_target_config request + /// Poll the execution of change_target_config request MegarepoChangeTargetConfigPollResponse megarepo_change_target_config_poll( 1: MegarepoChangeConfigToken token, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Sync commits up until cs_id source -> target + /// Sync commits up until cs_id source -> target MegarepoSyncChangesetToken megarepo_sync_changeset( 1: MegarepoSyncChangesetParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Poll the execution of sync_changeset request + /// Poll the execution of sync_changeset request MegarepoSyncChangesetPollResponse megarepo_sync_changeset_poll( 1: MegarepoSyncChangesetToken token, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Merge source into target from the `cs_id`, - // removing previous remapping of the source - // Returns a new position of the target bookmark - // This is how we handle non-forward bookmark moves - // in small repos - // Note: source may have moved from cs_id since - // this function was called, this function - // will merge `cs_id` into target - // Note: this fn will only succeed if target points - // to `target_location` by the time the fn - // advances the target + /// Merge source into target from the `cs_id`, + /// removing previous remapping of the source + /// Returns a new position of the target bookmark + /// This is how we handle non-forward bookmark moves + /// in small repos + /// Note: source may have moved from cs_id since + /// this function was called, this function + /// will merge `cs_id` into target + /// Note: this fn will only succeed if target points + /// to `target_location` by the time the fn + /// advances the target MegarepoRemergeSourceToken megarepo_remerge_source( 1: MegarepoRemergeSourceParams params, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Poll the execution of megarepo_re_merge_source request + /// Poll the execution of megarepo_re_merge_source request MegarepoRemergeSourcePollResponse megarepo_remerge_source_poll( 1: MegarepoRemergeSourceToken token, ) throws (1: RequestError request_error, 2: InternalError internal_error); - // Secret Methods - // ============== - // - // These are for internal Source Control Team use only, and may be removed - // without notice. + /// Secret Methods + /// ============== + /// + /// These are for internal Source Control Team use only, and may be removed + /// without notice. - // List a Hg manifest with Aux data + /// List a Hg manifest with Aux data RepoListHgManifestResponse repo_list_hg_manifest( 1: RepoSpecifier repo, 2: RepoListHgManifestParams params,