Fixing broken formatting/links in documentation. (#47)

Adding some very trivial docs as well. This is to make sure
auto-generated documentation looks sane.

2 files changed, 49 insertions, 26 deletions

diff --git a/build/bazel/remote/execution/v2/remote_execution.proto b/build/bazel/remote/execution/v2/remote_execution.proto
index 7e23c6d..0499471 100644
--- a/build/bazel/remote/execution/v2/remote_execution.proto
+++ b/build/bazel/remote/execution/v2/remote_execution.proto
@@ -81,6 +81,7 @@ service Execution {
   // action will be reported in the `status` field of the `ExecuteResponse`. The
   // server MUST NOT set the `error` field of the `Operation` proto.
   // The possible errors include:
+  //
   // * `INVALID_ARGUMENT`: One or more arguments are invalid.
   // * `FAILED_PRECONDITION`: One or more errors occurred in setting up the
   //   action requested, such as a missing input or command or no worker being
@@ -140,6 +141,7 @@ service ActionCache {
   // Retrieve a cached execution result.
   //
   // Errors:
+  //
   // * `NOT_FOUND`: The requested `ActionResult` is not in the cache.
   rpc GetActionResult(GetActionResultRequest) returns (ActionResult) {
     option (google.api.http) = { get: "/v2/{instance_name=**}/actionResults/{action_digest.hash}/{action_digest.size_bytes}" };
@@ -147,11 +149,6 @@ service ActionCache {
 
   // Upload a new execution result.
   //
-  // This method is intended for servers which implement the distributed cache
-  // independently of the
-  // [Execution][build.bazel.remote.execution.v2.Execution] API. As a
-  // result, it is OPTIONAL for servers to implement.
-  //
   // In order to allow the server to perform access control based on the type of
   // action, and to assist with client debugging, the client MUST first upload
   // the [Action][build.bazel.remote.execution.v2.Execution] that produced the
@@ -160,6 +157,7 @@ service ActionCache {
   // `ContentAddressableStorage`.
   //
   // Errors:
+  //
   // * `INVALID_ARGUMENT`: One or more arguments are invalid.
   // * `FAILED_PRECONDITION`: One or more errors occurred in updating the
   //   action result, such as a missing command or action.
@@ -263,10 +261,12 @@ service ContentAddressableStorage {
   // independently.
   //
   // Errors:
+  //
   // * `INVALID_ARGUMENT`: The client attempted to upload more than the
   //   server supported limit.
   //
   // Individual requests may return the following errors, additionally:
+  //
   // * `RESOURCE_EXHAUSTED`: There is insufficient disk quota to store the blob.
   // * `INVALID_ARGUMENT`: The
   // [Digest][build.bazel.remote.execution.v2.Digest] does not match the
@@ -289,6 +289,7 @@ service ContentAddressableStorage {
   // independently.
   //
   // Errors:
+  //
   // * `INVALID_ARGUMENT`: The client attempted to read more than the
   //   server supported limit.
   //
@@ -426,7 +427,8 @@ message Command {
   // provide its own default environment variables; these defaults can be
   // overridden using this field. Additional variables can also be specified.
   //
-  // In order to ensure that equivalent `Command`s always hash to the same
+  // In order to ensure that equivalent
+  // [Command][build.bazel.remote.execution.v2.Command]s always hash to the same
   // value, the environment variables MUST be lexicographically sorted by name.
   // Sorting of strings is done by code point, equivalently, by the UTF-8 bytes.
   repeated EnvironmentVariable environment_variables = 2;
@@ -543,12 +545,13 @@ message Platform {
 // In order to ensure that two equivalent directory trees hash to the same
 // value, the following restrictions MUST be obeyed when constructing a
 // a `Directory`:
-//   - Every child in the directory must have a path of exactly one segment.
-//     Multiple levels of directory hierarchy may not be collapsed.
-//   - Each child in the directory must have a unique path segment (file name).
-//   - The files, directories and symlinks in the directory must each be sorted
-//     in lexicographical order by path. The path strings must be sorted by code
-//     point, equivalently, by UTF-8 bytes.
+//
+// * Every child in the directory must have a path of exactly one segment.
+//   Multiple levels of directory hierarchy may not be collapsed.
+// * Each child in the directory must have a unique path segment (file name).
+// * The files, directories and symlinks in the directory must each be sorted
+//   in lexicographical order by path. The path strings must be sorted by code
+//   point, equivalently, by UTF-8 bytes.
 //
 // A `Directory` that obeys the restrictions is said to be in canonical form.
 //
@@ -668,11 +671,12 @@ message SymlinkNode {
 // When a `Digest` is used to refer to a proto message, it always refers to the
 // message in binary encoded form. To ensure consistent hashing, clients and
 // servers MUST ensure that they serialize messages according to the following
-// rules, even if there are alternate valid encodings for the same message.
-// - Fields are serialized in tag order.
-// - There are no unknown fields.
-// - There are no duplicate fields.
-// - Fields are serialized according to the default semantics for their type.
+// rules, even if there are alternate valid encodings for the same message:
+//
+// * Fields are serialized in tag order.
+// * There are no unknown fields.
+// * There are no duplicate fields.
+// * Fields are serialized according to the default semantics for their type.
 //
 // Most protocol buffer implementations will always follow these rules when
 // serializing, but care should be taken to avoid shortcuts. For instance,
@@ -739,7 +743,7 @@ message ActionResult {
   // The output files of the action that are symbolic links to other files. Those
   // may be links to other output files, or input files, or even absolute paths
   // outside of the working directory, if the server supports
-  // [SymlinkAbsolutePathStrategy.ALLOWED][build.bazel.remote.execution.v2.SymlinkAbsolutePathStrategy].
+  // [SymlinkAbsolutePathStrategy.ALLOWED][build.bazel.remote.execution.v2.CacheCapabilities.SymlinkAbsolutePathStrategy].
   // For each output file requested in the `output_files` field of the Action,
   // if the corresponding file existed after
   // the action completed, a single entry will be present either in this field,
@@ -816,7 +820,7 @@ message ActionResult {
   // directories. Those may be links to other output directories, or input
   // directories, or even absolute paths outside of the working directory,
   // if the server supports
-  // [SymlinkAbsolutePathStrategy.ALLOWED][build.bazel.remote.execution.v2.SymlinkAbsolutePathStrategy].
+  // [SymlinkAbsolutePathStrategy.ALLOWED][build.bazel.remote.execution.v2.CacheCapabilities.SymlinkAbsolutePathStrategy].
   // For each output directory requested in the `output_directories` field of
   // the Action, if the directory file existed after
   // the action completed, a single entry will be present either in this field,
@@ -1088,7 +1092,7 @@ message ExecuteOperationMetadata {
 // A request message for
 // [WaitExecution][build.bazel.remote.execution.v2.Execution.WaitExecution].
 message WaitExecutionRequest {
-  // The name of the [Operation][google.longrunning.operations.v1.Operation]
+  // The name of the [Operation][google.longrunning.Operation]
   // returned by [Execute][build.bazel.remote.execution.v2.Execution.Execute].
   string name = 1;
 }
@@ -1267,7 +1271,7 @@ message GetTreeResponse {
 }
 
 // A request message for
-// [Capabilities.GetCapabilities][google.devtools.remoteexecution.v2.Capabilities.GetCapabilities].
+// [Capabilities.GetCapabilities][build.bazel.remote.execution.v2.Capabilities.GetCapabilities].
 message GetCapabilitiesRequest {
   // The instance of the execution system to operate against. A server may
   // support multiple instances of the execution system (with their own workers,
@@ -1278,7 +1282,7 @@ message GetCapabilitiesRequest {
 }
 
 // A response message for
-// [Capabilities.GetCapabilities][google.devtools.remoteexecution.v2.Capabilities.GetCapabilities].
+// [Capabilities.GetCapabilities][build.bazel.remote.execution.v2.Capabilities.GetCapabilities].
 message ServerCapabilities {
   // Capabilities of the remote cache system.
   CacheCapabilities cache_capabilities = 1;
@@ -1299,9 +1303,16 @@ message ServerCapabilities {
 // The digest function used for converting values into keys for CAS and Action
 // Cache.
 enum DigestFunction {
+  // It is an error for the server to return this value.
   UNKNOWN = 0;
+
+  // The Sha-256 digest function.
   SHA256 = 1;
+
+  // The Sha-1 digest function.
   SHA1 = 2;
+
+  // The MD5 digest function.
   MD5 = 3;
 }
 
@@ -1328,9 +1339,10 @@ message CacheCapabilities {
   enum SymlinkAbsolutePathStrategy {
     UNKNOWN = 0;
 
-    // Server will return an INVALID_ARGUMENT on input symlinks with absolute targets.
+    // Server will return an `INVALID_ARGUMENT` on input symlinks with absolute
+    // targets.
     // If an action tries to create an output symlink with an absolute target, a
-    // FAILED_PRECONDITION will be returned.
+    // `FAILED_PRECONDITION` will be returned.
     DISALLOWED = 1;
 
     // Server will allow symlink targets to escape the input root tree, possibly
@@ -1383,8 +1395,9 @@ message ToolDetails {
 // external context of the request. The server may use this for logging or other
 // purposes. To use it, the client attaches the header to the call using the
 // canonical proto serialization:
-// name: build.bazel.remote.execution.v2.requestmetadata-bin
-// contents: the base64 encoded binary RequestMetadata message.
+//
+// * name: `build.bazel.remote.execution.v2.requestmetadata-bin`
+// * contents: the base64 encoded binary `RequestMetadata` message.
 message RequestMetadata {
   // The details for the tool invoking the requests.
   ToolDetails tool_details = 1;
diff --git a/build/bazel/semver/semver.proto b/build/bazel/semver/semver.proto
index 79f7b5f..3b626b7 100644
--- a/build/bazel/semver/semver.proto
+++ b/build/bazel/semver/semver.proto
@@ -23,9 +23,19 @@ option java_outer_classname = "SemverProto";
 option java_package = "build.bazel.semver";
 option objc_class_prefix = "SMV";
 
+// The full version of a given tool.
 message SemVer {
+  // The major version, e.g 10 for 10.2.3.
   int32 major = 1;
+
+  // The minor version, e.g. 2 for 10.2.3.
   int32 minor = 2;
+
+  // The patch version, e.g 3 for 10.2.3.
   int32 patch = 3;
+
+  // The pre-release version. Either this field or major/minor/patch fields
+  // must be filled. They are mutually exclusive. Pre-release versions are
+  // assumed to be earlier than any released versions.
   string prerelease = 4;
 }