Skip to content

Commit

Permalink
feat: generate behavior comments for fields
Browse files Browse the repository at this point in the history
`google.api.field_behavior` is used for describing field
behaviors for fields programmatically, instead of in comments. Because
they are not in comments, they wont be reflected in the generated
Typescript code. This change includes an appended behavior comment for
all fields that are annotated with field_behavior.

Proto3 `optional` do not have this comment appended, because the
generated types already sufficiently signals this.
  • Loading branch information
ericwenn committed Jul 7, 2021
1 parent 2a0fffe commit 4f8a18e
Show file tree
Hide file tree
Showing 2 changed files with 96 additions and 0 deletions.
66 changes: 66 additions & 0 deletions examples/proto/gen/typescript/einride/example/freight/v1/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -8,25 +8,43 @@ export type Shipment = {
// The resource name of the shipment.
name: string | undefined;
// The creation timestamp of the shipment.
//
// Behaviors: OUTPUT_ONLY
createTime: wellKnownTimestamp | undefined;
// The last update timestamp of the shipment.
// Updated when create/update/delete operation is shipment.
//
// Behaviors: OUTPUT_ONLY
updateTime: wellKnownTimestamp | undefined;
// The deletion timestamp of the shipment.
//
// Behaviors: OUTPUT_ONLY
deleteTime: wellKnownTimestamp | undefined;
// The resource name of the origin site of the shipment.
// Format: shippers/{shipper}/sites/{site}
//
// Behaviors: REQUIRED
originSite: string | undefined;
// The resource name of the destination site of the shipment.
// Format: shippers/{shipper}/sites/{site}
//
// Behaviors: REQUIRED
destinationSite: string | undefined;
// The earliest pickup time of the shipment at the origin site.
//
// Behaviors: REQUIRED
pickupEarliestTime: wellKnownTimestamp | undefined;
// The latest pickup time of the shipment at the origin site.
//
// Behaviors: REQUIRED
pickupLatestTime: wellKnownTimestamp | undefined;
// The earliest delivery time of the shipment at the destination site.
//
// Behaviors: REQUIRED
deliveryEarliestTime: wellKnownTimestamp | undefined;
// The latest delivery time of the shipment at the destination site.
//
// Behaviors: REQUIRED
deliveryLatestTime: wellKnownTimestamp | undefined;
// The line items of the shipment.
lineItems: LineItem[] | undefined;
Expand Down Expand Up @@ -56,13 +74,21 @@ export type Shipper = {
// The resource name of the shipper.
name: string | undefined;
// The creation timestamp of the shipper.
//
// Behaviors: OUTPUT_ONLY
createTime: wellKnownTimestamp | undefined;
// The last update timestamp of the shipper.
// Updated when create/update/delete operation is performed.
//
// Behaviors: OUTPUT_ONLY
updateTime: wellKnownTimestamp | undefined;
// The deletion timestamp of the shipper.
//
// Behaviors: OUTPUT_ONLY
deleteTime: wellKnownTimestamp | undefined;
// The display name of the shipper.
//
// Behaviors: REQUIRED
displayName: string | undefined;
};

Expand All @@ -72,13 +98,21 @@ export type Site = {
// The resource name of the site.
name: string | undefined;
// The creation timestamp of the site.
//
// Behaviors: OUTPUT_ONLY
createTime: wellKnownTimestamp | undefined;
// The last update timestamp of the site.
// Updated when create/update/delete operation is performed.
//
// Behaviors: OUTPUT_ONLY
updateTime: wellKnownTimestamp | undefined;
// The deletion timestamp of the site.
//
// Behaviors: OUTPUT_ONLY
deleteTime: wellKnownTimestamp | undefined;
// The display name of the site.
//
// Behaviors: REQUIRED
displayName: string | undefined;
// The geographic location of the site.
latLng: googletype_LatLng | undefined;
Expand All @@ -100,6 +134,8 @@ export type googletype_LatLng = {
export type GetShipperRequest = {
// The resource name of the shipper to retrieve.
// Format: shippers/{shipper}
//
// Behaviors: REQUIRED
name: string | undefined;
};

Expand Down Expand Up @@ -129,6 +165,8 @@ export type ListShippersResponse = {
// Request message for FreightService.CreateShipper.
export type CreateShipperRequest = {
// The shipper to create.
//
// Behaviors: REQUIRED
shipper: Shipper | undefined;
};

Expand All @@ -137,6 +175,8 @@ export type UpdateShipperRequest = {
// The shipper to update with. The name must match or be empty.
// The shipper's `name` field is used to identify the shipper to be updated.
// Format: shippers/{shipper}
//
// Behaviors: REQUIRED
shipper: Shipper | undefined;
// The list of fields to be updated.
updateMask: wellKnownFieldMask | undefined;
Expand Down Expand Up @@ -174,20 +214,26 @@ type wellKnownFieldMask = string;
export type DeleteShipperRequest = {
// The resource name of the shipper to delete.
// Format: shippers/{shipper}
//
// Behaviors: REQUIRED
name: string | undefined;
};

// Request message for FreightService.GetSite.
export type GetSiteRequest = {
// The resource name of the site to retrieve.
// Format: shippers/{shipper}/sites/{site}
//
// Behaviors: REQUIRED
name: string | undefined;
};

// Request message for FreightService.ListSites.
export type ListSitesRequest = {
// The resource name of the parent, which owns this collection of sites.
// Format: shippers/{shipper}
//
// Behaviors: REQUIRED
parent: string | undefined;
// Requested page size. Server may return fewer sites than requested.
// If unspecified, server will pick an appropriate default.
Expand All @@ -214,8 +260,12 @@ export type ListSitesResponse = {
export type CreateSiteRequest = {
// The resource name of the parent shipper for which this site will be created.
// Format: shippers/{shipper}
//
// Behaviors: REQUIRED
parent: string | undefined;
// The site to create.
//
// Behaviors: REQUIRED
site: Site | undefined;
};

Expand All @@ -224,6 +274,8 @@ export type UpdateSiteRequest = {
// The site to update with. The name must match or be empty.
// The site's `name` field is used to identify the site to be updated.
// Format: shippers/{shipper}/sites/{site}
//
// Behaviors: REQUIRED
site: Site | undefined;
// The list of fields to be updated.
updateMask: wellKnownFieldMask | undefined;
Expand All @@ -233,20 +285,26 @@ export type UpdateSiteRequest = {
export type DeleteSiteRequest = {
// The resource name of the site to delete.
// Format: shippers/{shipper}/sites/{site}
//
// Behaviors: REQUIRED
name: string | undefined;
};

// Request message for FreightService.GetShipment.
export type GetShipmentRequest = {
// The resource name of the shipment to retrieve.
// Format: shippers/{shipper}/shipments/{shipment}
//
// Behaviors: REQUIRED
name: string | undefined;
};

// Request message for FreightService.ListShipments.
export type ListShipmentsRequest = {
// The resource name of the parent, which owns this collection of shipments.
// Format: shippers/{shipper}
//
// Behaviors: REQUIRED
parent: string | undefined;
// Requested page size. Server may return fewer shipments than requested.
// If unspecified, server will pick an appropriate default.
Expand All @@ -273,8 +331,12 @@ export type ListShipmentsResponse = {
export type CreateShipmentRequest = {
// The resource name of the parent shipper for which this shipment will be created.
// Format: shippers/{shipper}
//
// Behaviors: REQUIRED
parent: string | undefined;
// The shipment to create.
//
// Behaviors: REQUIRED
shipment: Shipment | undefined;
};

Expand All @@ -283,6 +345,8 @@ export type UpdateShipmentRequest = {
// The shipment to update with. The name must match or be empty.
// The shipment's `name` field is used to identify the shipment to be updated.
// Format: shippers/{shipper}/shipments/{shipment}
//
// Behaviors: REQUIRED
shipment: Shipment | undefined;
// The list of fields to be updated.
updateMask: wellKnownFieldMask | undefined;
Expand All @@ -292,6 +356,8 @@ export type UpdateShipmentRequest = {
export type DeleteShipmentRequest = {
// The resource name of the shipment to delete.
// Format: shippers/{shipper}/shipments/{shipment}
//
// Behaviors: REQUIRED
name: string | undefined;
};

Expand Down
30 changes: 30 additions & 0 deletions internal/plugin/commentgen.go
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ import (
"strings"

"github.com/einride/protoc-gen-typescript-http/internal/codegen"
"google.golang.org/genproto/googleapis/api/annotations"
"google.golang.org/protobuf/proto"
"google.golang.org/protobuf/reflect/protoreflect"
)

Expand All @@ -20,4 +22,32 @@ func (c commentGenerator) generateLeading(f *codegen.File, indent int) {
}
f.P(t(indent), "// ", strings.TrimSpace(line))
}
if field, ok := c.descriptor.(protoreflect.FieldDescriptor); ok {
if behaviorComment := fieldBehaviorComment(field); len(behaviorComment) > 0 {
f.P(t(indent), "//")
f.P(t(indent), "// ", behaviorComment)
}
}
}

func fieldBehaviorComment(field protoreflect.FieldDescriptor) string {
behaviors := getFieldBehaviors(field)
if len(behaviors) == 0 {
return ""
}

behaviorStrings := make([]string, 0, len(behaviors))
for _, b := range behaviors {
behaviorStrings = append(behaviorStrings, b.String())
}
return "Behaviors: " + strings.Join(behaviorStrings, ", ")
}

func getFieldBehaviors(field protoreflect.FieldDescriptor) []annotations.FieldBehavior {
if behaviors, ok := proto.GetExtension(
field.Options(), annotations.E_FieldBehavior,
).([]annotations.FieldBehavior); ok {
return behaviors
}
return nil
}

0 comments on commit 4f8a18e

Please sign in to comment.