Updating Cloud Billing Budget API documentation for clarity.

PiperOrigin-RevId: 280225437

google/cloud/billing/budgets/v1beta1/billingbudgets.yaml

@@ -6,6 +6,12 @@ title: Cloud Billing Budget API
 apis:
 - name: google.cloud.billing.budgets.v1beta1.BudgetService
 
+documentation:
+  summary: |-
+    The Cloud Billing Budget API stores Cloud Billing budgets, which define a
+    budget plan and the rules to execute as spend is tracked against that
+    plan.
+
 authentication:
   rules:
   - selector: 'google.cloud.billing.budgets.v1beta1.BudgetService.*'

google/cloud/billing/budgets/v1beta1/budget_model.proto

@@ -25,9 +25,9 @@ option go_package = "google.golang.org/genproto/googleapis/cloud/billing/budgets
 option java_multiple_files = true;
 option java_package = "com.google.cloud.billing.budgets.v1beta1";
 
-// A budget is a plan that describes what the user expects to spend on Cloud
-// projects, plus rules to execute as spend is tracked against that plan,
-// e.g. alert at 90% of $100 target.
+// A budget is a plan that describes what you expect to spend on Cloud
+// projects, plus the rules to execute as spend is tracked against that plan,
+// (for example, send an alert when 90% of the target spend is met).
 // Currently all plans are monthly budgets so the usage period(s) tracked are
 // implied (calendar months of usage back-to-back).
 message Budget {
@@ -81,10 +81,11 @@ message BudgetAmount {
   }
 }
 
-// Describes a plan to target last period's spend.
-// There are no options yet. The amount is automatically 100% of last period's
-// spend.
-// Future configuration will go here (e.g. configuring the percentage).
+// Describes a budget amount targeted to last period's spend.
+// At this time, the amount is automatically 100% of last period's spend;
+// that is, there are no other options yet.
+// Future configuration will be described here (for example, configuring a
+// percentage of last period's spend).
 message LastPeriodAmount {
 
 }
@@ -92,9 +93,10 @@ message LastPeriodAmount {
 // ThresholdRule contains a definition of a threshold which triggers
 // an alert (a notification of a threshold being crossed) to be sent when
 // spend goes above the specified amount.
-// Alerts are automatically e-mailed to the billing users who have
-// access to the billing account. The thresholds here have no effect on
-// notifications sent to anything configured under `Budget.all_updates_rule`.
+// Alerts are automatically e-mailed to users with the Billing Account
+// Administrator role or the Billing Account User role.
+// The thresholds here have no effect on notifications sent to anything
+// configured under `Budget.all_updates_rule`.
 message ThresholdRule {
   // The type of basis used to determine if spend has passed the threshold.
   enum Basis {
@@ -125,7 +127,11 @@ message ThresholdRule {
 message AllUpdatesRule {
   // Required. The name of the Cloud Pub/Sub topic where budget related messages will be
   // published, in the form `projects/{project_id}/topics/{topic_id}`. Updates
-  // are sent at regular intervals to the topic. Caller is expected to have
+  // are sent at regular intervals to the topic.
+  // The topic needs to be created before the budget is created; see
+  // https://cloud.google.com/billing/docs/how-to/budgets#manage-notifications
+  // for more details.
+  // Caller is expected to have
   // `pubsub.topics.setIamPolicy` permission on the topic when it's set for a
   // budget, otherwise, the API call will fail with PERMISSION_DENIED. See
   // https://cloud.google.com/pubsub/docs/access-control for more details on

google/cloud/billing/budgets/v1beta1/budget_service.proto

@@ -35,8 +35,9 @@ service BudgetService {
   option (google.api.default_host) = "billingbudgets.googleapis.com";
   option (google.api.oauth_scopes) = "https://www.googleapis.com/auth/cloud-platform";
 
-  // Creates a new budget if none exists. There is a limit of 1,000 budgets
-  // per billing account.
+  // Creates a new budget. See
+  // <a href="https://cloud.google.com/billing/quotas">Quotas and limits</a>
+  // for more information on the limits of the number of budgets you can create.
   rpc CreateBudget(CreateBudgetRequest) returns (Budget) {
     option (google.api.http) = {
       post: "/v1beta1/{parent=billingAccounts/*}/budgets"
@@ -59,7 +60,7 @@ service BudgetService {
     };
   }
 
-  // Returns the budgets for a billing account.
+  // Returns a list of budgets for a billing account.
   rpc ListBudgets(ListBudgetsRequest) returns (ListBudgetsResponse) {
     option (google.api.http) = {
       get: "/v1beta1/{parent=billingAccounts/*}/budgets"
@@ -76,7 +77,7 @@ service BudgetService {
 
 // Request for CreateBudget
 message CreateBudgetRequest {
-  // Required. the name of the billing account to create the budget in. Values
+  // Required. The name of the billing account to create the budget in. Values
   // are of the form `billingAccounts/{billingAccountId}`.
   string parent = 1 [
     (google.api.field_behavior) = REQUIRED,