// Documentation annotation extension type.
//
// When the TARS proto-driven docs generator is wired up, the editorial
// title for each RPC's API-reference section is sourced from this
// annotation. Until then, the annotation records authorial intent
// alongside the proto.
//
// Field number 50004 mirrors IA's allocation. Field 50001 is used by
// `tars.auth.v1.auth`, 50002 by `tars.cli.v1.command`, 50005 by `group`.
syntax = "proto3";

package tars.docs.v1;

import "google/protobuf/descriptor.proto";

option go_package = "github.com/tetrateio/fraser/api/tars/docs/v1;docsv1";

extend google.protobuf.MethodOptions {
  // Editorial title for the endpoint's section in the generated API
  // reference, e.g. "Issue an API key" for MeService.IssueMyKey. When
  // empty, generators fall back to the humanized RPC name.
  string title = 50004;

  // Collapsible group label for the endpoint's section in the generated
  // API reference left-rail, e.g. "Workspaces" so all workspace RPCs nest
  // under one expandable heading. Endpoints sharing a group value are
  // rendered together under that heading; when empty, the endpoint renders
  // flat (ungrouped) at the top level of its service's navigation.
  string group = 50005;
}

extend google.protobuf.ServiceOptions {
  // internal marks a whole service as internal-only for documentation
  // purposes. When true, the API-reference generator always routes the
  // service into the internal tree and never the customer-facing tree,
  // REGARDLESS of each RPC's runtime auth annotation. This decouples doc
  // visibility from runtime auth: a service can accept API_KEY at runtime
  // (so SaaS dataplanes authenticate) yet stay out of the customer
  // reference. When false/absent, the generator falls back to per-RPC
  // auth-based classification.
  bool internal = 50004;
}
