Add comments to protobuf files about specifying ledgers

src/ripple/proto/org/xrpl/rpc/v1/get_account_info.proto

@@ -19,6 +19,11 @@ message GetAccountInfoRequest
 
     bool strict = 2;
 
+    // Which ledger to use to retrieve data.
+    // If this field is not set, the server will use the open ledger.
+    // The open ledger includes data that is not validated or final.
+    // To retrieve the most up to date and validated data, use
+    // SHORTCUT_VALIDATED
     LedgerSpecifier ledger = 3;
 
     bool queue = 4;

src/ripple/proto/org/xrpl/rpc/v1/get_account_transaction_history.proto

@@ -16,6 +16,13 @@ message GetAccountTransactionHistoryRequest
     // What ledger to include results from. Specifying a not yet validated
     // ledger results in an error. Not specifying a ledger uses the entire
     // range of validated ledgers available to the server.
+    // Note, this parameter acts as a filter, and can only reduce the number of
+    // results. Specifying a single ledger will return only transactions from
+    // that ledger. This includes specifying a ledger with a Shortcut. For
+    // example, specifying SHORTCUT_VALIDATED will result in only transactions
+    // that were part of the most recently validated ledger being returned.
+    // Specifying a range of ledgers results in only transactions that were
+    // included in a ledger within the specified range being returned.
     oneof ledger
     {
         LedgerSpecifier ledger_specifier = 2;

src/ripple/proto/org/xrpl/rpc/v1/get_transaction.proto

@@ -23,7 +23,11 @@ message GetTransactionRequest {
     // if true, return data in binary format. defaults to false
     bool binary = 2;
 
-    // search only specified range. optional
+    // If the transaction was not found, server will report whether the entire
+    // specified range was searched. The value is contained in the error message.
+    // The error message is of the form:
+    // "txn not found. searched_all = [true,false]"
+    // If the transaction was found, this parameter is ignored.
     LedgerRange ledger_range = 3;
 }
 

src/ripple/proto/org/xrpl/rpc/v1/xrp_ledger.proto

@@ -12,6 +12,7 @@ import "org/xrpl/rpc/v1/get_account_transaction_history.proto";
 
 
 // RPCs available to interact with the XRP Ledger.
+// The gRPC API mimics the JSON API. Refer to xrpl.org for documentation
 service XRPLedgerAPIService {
 
   // Get account info for an account on the XRP Ledger.
@@ -26,5 +27,6 @@ service XRPLedgerAPIService {
   // Get the status of a transaction
   rpc GetTransaction(GetTransactionRequest) returns (GetTransactionResponse);
 
+  // Get all validated transactions associated with a given account
   rpc GetAccountTransactionHistory(GetAccountTransactionHistoryRequest) returns (GetAccountTransactionHistoryResponse);
 }