From fcb7318eb338bf3828ac831ed06ca630e1876418 Mon Sep 17 00:00:00 2001 From: Tyler Bui-Palsulich <26876514+tbpg@users.noreply.github.com> Date: Tue, 2 Feb 2021 16:39:31 -0500 Subject: [PATCH] feat(internal/docfx): full cross reference linking (#3656) --- internal/godocfx/parse.go | 11 +- internal/godocfx/testdata/golden/index.yml | 823 ++++++++++++--------- third_party/pkgsite/print_type.go | 119 ++- 3 files changed, 585 insertions(+), 368 deletions(-) diff --git a/internal/godocfx/parse.go b/internal/godocfx/parse.go index 27f1d8d4eba..6f269116abc 100644 --- a/internal/godocfx/parse.go +++ b/internal/godocfx/parse.go @@ -15,7 +15,6 @@ // +build go1.15 // TODO: -// pkgsite.PrintType doesn't linkify. // IDs for const/var groups have every name, not just the one to link to. // Preserve IDs when sanitizing then use the right ID for linking. // Link to different domains by pattern (e.g. for cloud.google.com/go). @@ -182,7 +181,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result Type: "const", Summary: c.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(pi.fset, c.Decl)}, + Syntax: syntax{Content: pkgsite.PrintType(pi.fset, c.Decl, toURL)}, }) } for _, v := range pi.doc.Vars { @@ -198,7 +197,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result Type: "variable", Summary: v.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(pi.fset, v.Decl)}, + Syntax: syntax{Content: pkgsite.PrintType(pi.fset, v.Decl, toURL)}, }) } for _, t := range pi.doc.Types { @@ -212,7 +211,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result Type: "type", Summary: t.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(pi.fset, t.Decl)}, + Syntax: syntax{Content: pkgsite.PrintType(pi.fset, t.Decl, toURL)}, Examples: processExamples(t.Examples, pi.fset), } // Note: items are added as page.Children, rather than @@ -231,7 +230,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result Type: "const", Summary: c.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(pi.fset, c.Decl)}, + Syntax: syntax{Content: pkgsite.PrintType(pi.fset, c.Decl, toURL)}, }) } for _, v := range t.Vars { @@ -247,7 +246,7 @@ func parse(glob string, workingDir string, optionalExtraFiles []string) (*result Type: "variable", Summary: v.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(pi.fset, v.Decl)}, + Syntax: syntax{Content: pkgsite.PrintType(pi.fset, v.Decl, toURL)}, }) } diff --git a/internal/godocfx/testdata/golden/index.yml b/internal/godocfx/testdata/golden/index.yml index 7527a926602..cd10f67f251 100644 --- a/internal/godocfx/testdata/golden/index.yml +++ b/internal/godocfx/testdata/golden/index.yml @@ -282,10 +282,14 @@ items: - go syntax: content: "const (\n\t// ScopeFullControl grants permissions to manage your\n\t// - data and permissions in Google Cloud Storage.\n\tScopeFullControl = raw.DevstorageFullControlScope\n\n\t// + data and permissions in Google Cloud Storage.\n\tScopeFullControl = raw.DevstorageFullControlScope\n\n\t// ScopeReadOnly grants permissions to\n\t// view your data in Google Cloud Storage.\n\tScopeReadOnly - = raw.DevstorageReadOnlyScope\n\n\t// ScopeReadWrite grants permissions to manage - your\n\t// data in Google Cloud Storage.\n\tScopeReadWrite = raw.DevstorageReadWriteScope\n)" + = raw.DevstorageReadOnlyScope\n\n\t// + ScopeReadWrite grants permissions to manage your\n\t// data in Google Cloud + Storage.\n\tScopeReadWrite = raw.DevstorageReadWriteScope\n)" - uid: cloud.google.com/go/storage.ErrBucketNotExist,ErrObjectNotExist name: ErrBucketNotExist, ErrObjectNotExist id: ErrBucketNotExist,ErrObjectNotExist @@ -295,9 +299,10 @@ items: - go syntax: content: "var (\n\t// ErrBucketNotExist indicates that the bucket does not exist.\n\tErrBucketNotExist - = errors.New(\"storage: bucket doesn't exist\")\n\t// ErrObjectNotExist indicates - that the object does not exist.\n\tErrObjectNotExist = errors.New(\"storage: - object doesn't exist\")\n)" + = errors.New(\"storage: + bucket doesn't exist\")\n\t// ErrObjectNotExist indicates that the object does + not exist.\n\tErrObjectNotExist = errors.New(\"storage: object doesn't exist\")\n)" - uid: cloud.google.com/go/storage.ACLEntity name: ACLEntity id: ACLEntity @@ -315,7 +320,7 @@ items: langs: - go syntax: - content: type ACLEntity string + content: type ACLEntity string - uid: cloud.google.com/go/storage.AllUsers,AllAuthenticatedUsers name: AllUsers, AllAuthenticatedUsers id: AllUsers,AllAuthenticatedUsers @@ -324,8 +329,9 @@ items: langs: - go syntax: - content: "const (\n\tAllUsers ACLEntity = \"allUsers\"\n\tAllAuthenticatedUsers - ACLEntity = \"allAuthenticatedUsers\"\n)" + content: "const (\n\tAllUsers ACLEntity + = \"allUsers\"\n\tAllAuthenticatedUsers ACLEntity + = \"allAuthenticatedUsers\"\n)" - uid: cloud.google.com/go/storage.ACLHandle name: ACLHandle id: ACLHandle @@ -408,7 +414,7 @@ items: langs: - go syntax: - content: type ACLRole string + content: type ACLRole string - uid: cloud.google.com/go/storage.RoleOwner,RoleReader,RoleWriter name: RoleOwner, RoleReader, RoleWriter id: RoleOwner,RoleReader,RoleWriter @@ -417,8 +423,9 @@ items: langs: - go syntax: - content: "const (\n\tRoleOwner ACLRole = \"OWNER\"\n\tRoleReader ACLRole = \"READER\"\n\tRoleWriter - ACLRole = \"WRITER\"\n)" + content: "const (\n\tRoleOwner ACLRole = \"OWNER\"\n\tRoleReader + ACLRole = \"READER\"\n\tRoleWriter ACLRole + = \"WRITER\"\n)" - uid: cloud.google.com/go/storage.ACLRule name: ACLRule id: ACLRule @@ -430,8 +437,11 @@ items: langs: - go syntax: - content: "type ACLRule struct {\n\tEntity ACLEntity\n\tEntityID string\n\tRole - \ ACLRole\n\tDomain string\n\tEmail string\n\tProjectTeam *ProjectTeam\n}" + content: "type ACLRule struct {\n\tEntity ACLEntity\n\tEntityID + \ string\n\tRole ACLRole\n\tDomain string\n\tEmail + \ string\n\tProjectTeam + *ProjectTeam\n}" - uid: cloud.google.com/go/storage.BucketAttrs name: BucketAttrs id: BucketAttrs @@ -444,54 +454,63 @@ items: - go syntax: content: "type BucketAttrs struct {\n\t// Name is the name of the bucket.\n\t// - This field is read-only.\n\tName string\n\n\t// ACL is the list of access control - rules on the bucket.\n\tACL []ACLRule\n\n\t// BucketPolicyOnly is an alias for - UniformBucketLevelAccess. Use of\n\t// UniformBucketLevelAccess is recommended - above the use of this field.\n\t// Setting BucketPolicyOnly.Enabled OR UniformBucketLevelAccess.Enabled - to\n\t// true, will enable UniformBucketLevelAccess.\n\tBucketPolicyOnly BucketPolicyOnly\n\n\t// - UniformBucketLevelAccess configures access checks to use only bucket-level IAM\n\t// - policies and ignore any ACL rules for the bucket.\n\t// See https://cloud.google.com/storage/docs/uniform-bucket-level-access\n\t// - for more information.\n\tUniformBucketLevelAccess UniformBucketLevelAccess\n\n\t// + This field is read-only.\n\tName string\n\n\t// + ACL is the list of access control rules on the bucket.\n\tACL []ACLRule\n\n\t// + BucketPolicyOnly is an alias for UniformBucketLevelAccess. Use of\n\t// UniformBucketLevelAccess + is recommended above the use of this field.\n\t// Setting BucketPolicyOnly.Enabled + OR UniformBucketLevelAccess.Enabled to\n\t// true, will enable UniformBucketLevelAccess.\n\tBucketPolicyOnly + BucketPolicyOnly\n\n\t// UniformBucketLevelAccess + configures access checks to use only bucket-level IAM\n\t// policies and ignore + any ACL rules for the bucket.\n\t// See https://cloud.google.com/storage/docs/uniform-bucket-level-access\n\t// + for more information.\n\tUniformBucketLevelAccess UniformBucketLevelAccess\n\n\t// DefaultObjectACL is the list of access controls to\n\t// apply to new objects - when no object ACL is provided.\n\tDefaultObjectACL []ACLRule\n\n\t// DefaultEventBasedHold - is the default value for event-based hold on\n\t// newly created objects in - this bucket. It defaults to false.\n\tDefaultEventBasedHold bool\n\n\t// If - not empty, applies a predefined set of access controls. It should be set\n\t// - only when creating a bucket.\n\t// It is always empty for BucketAttrs returned - from the service.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/insert\n\t// - for valid values.\n\tPredefinedACL string\n\n\t// If not empty, applies a predefined - set of default object access controls.\n\t// It should be set only when creating + when no object ACL is provided.\n\tDefaultObjectACL []ACLRule\n\n\t// + DefaultEventBasedHold is the default value for event-based hold on\n\t// newly + created objects in this bucket. It defaults to false.\n\tDefaultEventBasedHold + bool\n\n\t// If not empty, applies + a predefined set of access controls. It should be set\n\t// only when creating a bucket.\n\t// It is always empty for BucketAttrs returned from the service.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/insert\n\t// for - valid values.\n\tPredefinedDefaultObjectACL string\n\n\t// Location is the location - of the bucket. It defaults to \"US\".\n\tLocation string\n\n\t// MetaGeneration + valid values.\n\tPredefinedACL string\n\n\t// + If not empty, applies a predefined set of default object access controls.\n\t// + It should be set only when creating a bucket.\n\t// It is always empty for BucketAttrs + returned from the service.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/insert\n\t// + for valid values.\n\tPredefinedDefaultObjectACL string\n\n\t// + Location is the location of the bucket. It defaults to \"US\".\n\tLocation string\n\n\t// MetaGeneration is the metadata generation of the bucket.\n\t// This field is read-only.\n\tMetaGeneration - int64\n\n\t// StorageClass is the default storage class of the bucket. This - defines\n\t// how objects in the bucket are stored and determines the SLA\n\t// - and the cost of storage. Typical values are \"STANDARD\", \"NEARLINE\",\n\t// - \"COLDLINE\" and \"ARCHIVE\". Defaults to \"STANDARD\".\n\t// See https://cloud.google.com/storage/docs/storage-classes - for all\n\t// valid values.\n\tStorageClass string\n\n\t// Created is the creation - time of the bucket.\n\t// This field is read-only.\n\tCreated time.Time\n\n\t// + int64\n\n\t// StorageClass + is the default storage class of the bucket. This defines\n\t// how objects in + the bucket are stored and determines the SLA\n\t// and the cost of storage. + Typical values are \"STANDARD\", \"NEARLINE\",\n\t// \"COLDLINE\" and \"ARCHIVE\". + Defaults to \"STANDARD\".\n\t// See https://cloud.google.com/storage/docs/storage-classes + for all\n\t// valid values.\n\tStorageClass string\n\n\t// + Created is the creation time of the bucket.\n\t// This field is read-only.\n\tCreated + time.Time\n\n\t// VersioningEnabled reports whether this bucket has versioning enabled.\n\tVersioningEnabled - bool\n\n\t// Labels are the bucket's labels.\n\tLabels map[string]string\n\n\t// - RequesterPays reports whether the bucket is a Requester Pays bucket.\n\t// Clients - performing operations on Requester Pays buckets must provide\n\t// a user project - (see BucketHandle.UserProject), which will be billed\n\t// for the operations.\n\tRequesterPays - bool\n\n\t// Lifecycle is the lifecycle configuration for objects in the bucket.\n\tLifecycle - Lifecycle\n\n\t// Retention policy enforces a minimum retention time for all - objects\n\t// contained in the bucket. A RetentionPolicy of nil implies the - bucket\n\t// has no minimum data retention.\n\t//\n\t// This feature is in private - alpha release. It is not currently available to\n\t// most customers. It might - be changed in backwards-incompatible ways and is not\n\t// subject to any SLA - or deprecation policy.\n\tRetentionPolicy *RetentionPolicy\n\n\t// The bucket's - Cross-Origin Resource Sharing (CORS) configuration.\n\tCORS []CORS\n\n\t// The - encryption configuration used by default for newly inserted objects.\n\tEncryption - *BucketEncryption\n\n\t// The logging configuration.\n\tLogging *BucketLogging\n\n\t// - The website configuration.\n\tWebsite *BucketWebsite\n\n\t// Etag is the HTTP/1.1 - Entity tag for the bucket.\n\t// This field is read-only.\n\tEtag string\n\n\t// + bool\n\n\t// Labels are the + bucket's labels.\n\tLabels map[string]string\n\n\t// RequesterPays + reports whether the bucket is a Requester Pays bucket.\n\t// Clients performing + operations on Requester Pays buckets must provide\n\t// a user project (see + BucketHandle.UserProject), which will be billed\n\t// for the operations.\n\tRequesterPays + bool\n\n\t// Lifecycle is the + lifecycle configuration for objects in the bucket.\n\tLifecycle Lifecycle\n\n\t// + Retention policy enforces a minimum retention time for all objects\n\t// contained + in the bucket. A RetentionPolicy of nil implies the bucket\n\t// has no minimum + data retention.\n\t//\n\t// This feature is in private alpha release. It is + not currently available to\n\t// most customers. It might be changed in backwards-incompatible + ways and is not\n\t// subject to any SLA or deprecation policy.\n\tRetentionPolicy + *RetentionPolicy\n\n\t// The bucket's Cross-Origin + Resource Sharing (CORS) configuration.\n\tCORS []CORS\n\n\t// + The encryption configuration used by default for newly inserted objects.\n\tEncryption + *BucketEncryption\n\n\t// The logging configuration.\n\tLogging + *BucketLogging\n\n\t// The website configuration.\n\tWebsite + *BucketWebsite\n\n\t// Etag is the HTTP/1.1 Entity + tag for the bucket.\n\t// This field is read-only.\n\tEtag string\n\n\t// LocationType describes how data is stored and replicated.\n\t// Typical values are \"multi-region\", \"region\" and \"dual-region\".\n\t// This field is read-only.\n\tLocationType - string\n}" + string\n}" - uid: cloud.google.com/go/storage.BucketAttrsToUpdate name: BucketAttrsToUpdate id: BucketAttrsToUpdate @@ -503,35 +522,42 @@ items: - go syntax: content: "type BucketAttrsToUpdate struct {\n\t// If set, updates whether the - bucket uses versioning.\n\tVersioningEnabled optional.Bool\n\n\t// If set, updates - whether the bucket is a Requester Pays bucket.\n\tRequesterPays optional.Bool\n\n\t// + bucket uses versioning.\n\tVersioningEnabled optional.Bool\n\n\t// + If set, updates whether the bucket is a Requester Pays bucket.\n\tRequesterPays + optional.Bool\n\n\t// DefaultEventBasedHold is the default value for event-based hold on\n\t// newly - created objects in this bucket.\n\tDefaultEventBasedHold optional.Bool\n\n\t// + created objects in this bucket.\n\tDefaultEventBasedHold optional.Bool\n\n\t// BucketPolicyOnly is an alias for UniformBucketLevelAccess. Use of\n\t// UniformBucketLevelAccess is recommended above the use of this field.\n\t// Setting BucketPolicyOnly.Enabled OR UniformBucketLevelAccess.Enabled to\n\t// true, will enable UniformBucketLevelAccess. If both BucketPolicyOnly and\n\t// UniformBucketLevelAccess are set, the value of UniformBucketLevelAccess\n\t// will take precedence.\n\tBucketPolicyOnly - *BucketPolicyOnly\n\n\t// UniformBucketLevelAccess configures access checks - to use only bucket-level IAM\n\t// policies and ignore any ACL rules for the - bucket.\n\t// See https://cloud.google.com/storage/docs/uniform-bucket-level-access\n\t// - for more information.\n\tUniformBucketLevelAccess *UniformBucketLevelAccess\n\n\t// + *BucketPolicyOnly\n\n\t// UniformBucketLevelAccess + configures access checks to use only bucket-level IAM\n\t// policies and ignore + any ACL rules for the bucket.\n\t// See https://cloud.google.com/storage/docs/uniform-bucket-level-access\n\t// + for more information.\n\tUniformBucketLevelAccess *UniformBucketLevelAccess\n\n\t// If set, updates the retention policy of the bucket. Using\n\t// RetentionPolicy.RetentionPeriod = 0 will delete the existing policy.\n\t//\n\t// This feature is in private alpha release. It is not currently available to\n\t// most customers. It might be changed in backwards-incompatible ways and is not\n\t// subject to any SLA - or deprecation policy.\n\tRetentionPolicy *RetentionPolicy\n\n\t// If set, replaces - the CORS configuration with a new configuration.\n\t// An empty (rather than - nil) slice causes all CORS policies to be removed.\n\tCORS []CORS\n\n\t// If - set, replaces the encryption configuration of the bucket. Using\n\t// BucketEncryption.DefaultKMSKeyName - = \"\" will delete the existing\n\t// configuration.\n\tEncryption *BucketEncryption\n\n\t// - If set, replaces the lifecycle configuration of the bucket.\n\tLifecycle *Lifecycle\n\n\t// - If set, replaces the logging configuration of the bucket.\n\tLogging *BucketLogging\n\n\t// - If set, replaces the website configuration of the bucket.\n\tWebsite *BucketWebsite\n\n\t// + or deprecation policy.\n\tRetentionPolicy *RetentionPolicy\n\n\t// + If set, replaces the CORS configuration with a new configuration.\n\t// An empty + (rather than nil) slice causes all CORS policies to be removed.\n\tCORS []CORS\n\n\t// If set, replaces the encryption configuration + of the bucket. Using\n\t// BucketEncryption.DefaultKMSKeyName = \"\" will delete + the existing\n\t// configuration.\n\tEncryption *BucketEncryption\n\n\t// + If set, replaces the lifecycle configuration of the bucket.\n\tLifecycle *Lifecycle\n\n\t// If set, replaces the logging configuration + of the bucket.\n\tLogging *BucketLogging\n\n\t// + If set, replaces the website configuration of the bucket.\n\tWebsite *BucketWebsite\n\n\t// If not empty, applies a predefined set of access controls.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/patch.\n\tPredefinedACL - string\n\n\t// If not empty, applies a predefined set of default object access - controls.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/patch.\n\tPredefinedDefaultObjectACL - string\n\t// contains filtered or unexported fields\n}" + string\n\n\t// If not empty, + applies a predefined set of default object access controls.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/buckets/patch.\n\tPredefinedDefaultObjectACL + string\n\t// contains filtered + or unexported fields\n}" - uid: cloud.google.com/go/storage.BucketAttrsToUpdate.DeleteLabel name: | func (*BucketAttrsToUpdate) DeleteLabel @@ -574,10 +600,11 @@ items: syntax: content: "type BucketConditions struct {\n\t// MetagenerationMatch specifies that the bucket must have the given\n\t// metageneration for the operation to occur.\n\t// - If MetagenerationMatch is zero, it has no effect.\n\tMetagenerationMatch int64\n\n\t// - MetagenerationNotMatch specifies that the bucket must not have the given\n\t// - metageneration for the operation to occur.\n\t// If MetagenerationNotMatch is - zero, it has no effect.\n\tMetagenerationNotMatch int64\n}" + If MetagenerationMatch is zero, it has no effect.\n\tMetagenerationMatch int64\n\n\t// MetagenerationNotMatch + specifies that the bucket must not have the given\n\t// metageneration for the + operation to occur.\n\t// If MetagenerationNotMatch is zero, it has no effect.\n\tMetagenerationNotMatch + int64\n}" - uid: cloud.google.com/go/storage.BucketEncryption name: BucketEncryption id: BucketEncryption @@ -591,7 +618,8 @@ items: content: "type BucketEncryption struct {\n\t// A Cloud KMS key name, in the form\n\t// projects/P/locations/L/keyRings/R/cryptoKeys/K, that will be used to encrypt\n\t// objects inserted into this bucket, if no encryption method is specified.\n\t// - The key's location must be the same as the bucket's.\n\tDefaultKMSKeyName string\n}" + The key's location must be the same as the bucket's.\n\tDefaultKMSKeyName string\n}" - uid: cloud.google.com/go/storage.BucketHandle name: BucketHandle id: BucketHandle @@ -925,8 +953,8 @@ items: - go syntax: content: "type BucketIterator struct {\n\t// Prefix restricts the iterator to - buckets whose names begin with it.\n\tPrefix string\n\t// contains filtered - or unexported fields\n}" + buckets whose names begin with it.\n\tPrefix string\n\t// + contains filtered or unexported fields\n}" - uid: cloud.google.com/go/storage.BucketIterator.Next name: | func (*BucketIterator) Next @@ -978,8 +1006,8 @@ items: - go syntax: content: "type BucketLogging struct {\n\t// The destination bucket where the current - bucket's logs\n\t// should be placed.\n\tLogBucket string\n\n\t// A prefix for - log object names.\n\tLogObjectPrefix string\n}" + bucket's logs\n\t// should be placed.\n\tLogBucket string\n\n\t// + A prefix for log object names.\n\tLogObjectPrefix string\n}" - uid: cloud.google.com/go/storage.BucketPolicyOnly name: BucketPolicyOnly id: BucketPolicyOnly @@ -993,8 +1021,9 @@ items: syntax: content: "type BucketPolicyOnly struct {\n\t// Enabled specifies whether access checks use only bucket-level IAM\n\t// policies. Enabled may be disabled until - the locked time.\n\tEnabled bool\n\t// LockedTime specifies the deadline for - changing Enabled from true to\n\t// false.\n\tLockedTime time.Time\n}" + the locked time.\n\tEnabled bool\n\t// + LockedTime specifies the deadline for changing Enabled from true to\n\t// false.\n\tLockedTime + time.Time\n}" - uid: cloud.google.com/go/storage.BucketWebsite name: BucketWebsite id: BucketWebsite @@ -1011,10 +1040,10 @@ items: the service will ensure the path has\n\t// a trailing '/', append this suffix, and attempt to retrieve the resulting\n\t// object. This allows the creation of index.html objects to represent directory\n\t// pages.\n\tMainPageSuffix - string\n\n\t// If the requested object path is missing, and any mainPageSuffix - object is\n\t// missing, if applicable, the service will return the named object - from this\n\t// bucket as the content for a 404 Not Found result.\n\tNotFoundPage - string\n}" + string\n\n\t// If the requested + object path is missing, and any mainPageSuffix object is\n\t// missing, if applicable, + the service will return the named object from this\n\t// bucket as the content + for a 404 Not Found result.\n\tNotFoundPage string\n}" - uid: cloud.google.com/go/storage.CORS name: CORS id: CORS @@ -1026,15 +1055,17 @@ items: - go syntax: content: "type CORS struct {\n\t// MaxAge is the value to return in the Access-Control-Max-Age\n\t// - header used in preflight responses.\n\tMaxAge time.Duration\n\n\t// Methods - is the list of HTTP methods on which to include CORS response\n\t// headers, - (GET, OPTIONS, POST, etc) Note: \"*\" is permitted in the list\n\t// of methods, - and means \"any method\".\n\tMethods []string\n\n\t// Origins is the list of - Origins eligible to receive CORS response\n\t// headers. Note: \"*\" is permitted - in the list of origins, and means\n\t// \"any Origin\".\n\tOrigins []string\n\n\t// - ResponseHeaders is the list of HTTP headers other than the simple\n\t// response - headers to give permission for the user-agent to share\n\t// across domains.\n\tResponseHeaders - []string\n}" + header used in preflight responses.\n\tMaxAge time.Duration\n\n\t// Methods is the + list of HTTP methods on which to include CORS response\n\t// headers, (GET, + OPTIONS, POST, etc) Note: \"*\" is permitted in the list\n\t// of methods, and + means \"any method\".\n\tMethods []string\n\n\t// + Origins is the list of Origins eligible to receive CORS response\n\t// headers. + Note: \"*\" is permitted in the list of origins, and means\n\t// \"any Origin\".\n\tOrigins + []string\n\n\t// ResponseHeaders + is the list of HTTP headers other than the simple\n\t// response headers to + give permission for the user-agent to share\n\t// across domains.\n\tResponseHeaders + []string\n}" - uid: cloud.google.com/go/storage.Client name: Client id: Client @@ -1246,13 +1277,14 @@ items: syntax: content: "type Composer struct {\n\t// ObjectAttrs are optional attributes to set on the destination object.\n\t// Any attributes must be initialized before - any calls on the Composer. Nil\n\t// or zero-valued attributes are ignored.\n\tObjectAttrs\n\n\t// - SendCRC specifies whether to transmit a CRC32C field. It should be set\n\t// - to true in addition to setting the Composer's CRC32C field, because zero\n\t// - is a valid CRC and normally a zero would not be transmitted.\n\t// If a CRC32C - is sent, and the data in the destination object does not match\n\t// the checksum, - the compose will be rejected.\n\tSendCRC32C bool\n\t// contains filtered or - unexported fields\n}" + any calls on the Composer. Nil\n\t// or zero-valued attributes are ignored.\n\tObjectAttrs\n\n\t// SendCRC specifies whether to transmit + a CRC32C field. It should be set\n\t// to true in addition to setting the Composer's + CRC32C field, because zero\n\t// is a valid CRC and normally a zero would not + be transmitted.\n\t// If a CRC32C is sent, and the data in the destination object + does not match\n\t// the checksum, the compose will be rejected.\n\tSendCRC32C + bool\n\t// contains filtered + or unexported fields\n}" - uid: cloud.google.com/go/storage.Composer.Run name: | func (*Composer) Run @@ -1297,17 +1329,19 @@ items: content: "type Conditions struct {\n\n\t// GenerationMatch specifies that the object must have the given generation\n\t// for the operation to occur.\n\t// If GenerationMatch is zero, it has no effect.\n\t// Use DoesNotExist to specify - that the object does not exist in the bucket.\n\tGenerationMatch int64\n\n\t// + that the object does not exist in the bucket.\n\tGenerationMatch int64\n\n\t// GenerationNotMatch specifies that the object must not have the given\n\t// generation for the operation to occur.\n\t// If GenerationNotMatch is zero, it has no effect.\n\tGenerationNotMatch - int64\n\n\t// DoesNotExist specifies that the object must not exist in the bucket - for\n\t// the operation to occur.\n\t// If DoesNotExist is false, it has no - effect.\n\tDoesNotExist bool\n\n\t// MetagenerationMatch specifies that the - object must have the given\n\t// metageneration for the operation to occur.\n\t// - If MetagenerationMatch is zero, it has no effect.\n\tMetagenerationMatch int64\n\n\t// - MetagenerationNotMatch specifies that the object must not have the given\n\t// - metageneration for the operation to occur.\n\t// If MetagenerationNotMatch is - zero, it has no effect.\n\tMetagenerationNotMatch int64\n}" + int64\n\n\t// DoesNotExist + specifies that the object must not exist in the bucket for\n\t// the operation + to occur.\n\t// If DoesNotExist is false, it has no effect.\n\tDoesNotExist + bool\n\n\t// MetagenerationMatch + specifies that the object must have the given\n\t// metageneration for the operation + to occur.\n\t// If MetagenerationMatch is zero, it has no effect.\n\tMetagenerationMatch + int64\n\n\t// MetagenerationNotMatch + specifies that the object must not have the given\n\t// metageneration for the + operation to occur.\n\t// If MetagenerationNotMatch is zero, it has no effect.\n\tMetagenerationNotMatch + int64\n}" - uid: cloud.google.com/go/storage.Copier name: Copier id: Copier @@ -1320,10 +1354,11 @@ items: syntax: content: "type Copier struct {\n\t// ObjectAttrs are optional attributes to set on the destination object.\n\t// Any attributes must be initialized before any - calls on the Copier. Nil\n\t// or zero-valued attributes are ignored.\n\tObjectAttrs\n\n\t// - RewriteToken can be set before calling Run to resume a copy\n\t// operation. - After Run returns a non-nil error, RewriteToken will\n\t// have been updated - to contain the value needed to resume the copy.\n\tRewriteToken string\n\n\t// + calls on the Copier. Nil\n\t// or zero-valued attributes are ignored.\n\tObjectAttrs\n\n\t// RewriteToken can be set before + calling Run to resume a copy\n\t// operation. After Run returns a non-nil error, + RewriteToken will\n\t// have been updated to contain the value needed to resume + the copy.\n\tRewriteToken string\n\n\t// ProgressFunc can be used to monitor the progress of a multi-RPC copy\n\t// operation. If ProgressFunc is not nil and copying requires multiple\n\t// calls to the underlying service (see\n\t// https://cloud.google.com/storage/docs/json_api/v1/objects/rewrite), @@ -1333,11 +1368,12 @@ items: For example, the implementation of ProgressFunc may update\n\t// a progress bar in the application's UI, or log the result of\n\t// float64(copiedBytes)/float64(totalBytes).\n\t//\n\t// ProgressFunc should return quickly without blocking.\n\tProgressFunc func(copiedBytes, - totalBytes uint64)\n\n\t// The Cloud KMS key, in the form projects/P/locations/L/keyRings/R/cryptoKeys/K,\n\t// + totalBytes uint64)\n\n\t// + The Cloud KMS key, in the form projects/P/locations/L/keyRings/R/cryptoKeys/K,\n\t// that will be used to encrypt the object. Overrides the object's KMSKeyName, if\n\t// any.\n\t//\n\t// Providing both a DestinationKMSKeyName and a customer-supplied encryption key\n\t// (via ObjectHandle.Key) on the destination object will result - in an error when\n\t// Run is called.\n\tDestinationKMSKeyName string\n\t// + in an error when\n\t// Run is called.\n\tDestinationKMSKeyName string\n\t// contains filtered or unexported fields\n}" - uid: cloud.google.com/go/storage.Copier.Run name: | @@ -1386,17 +1422,21 @@ items: langs: - go syntax: - content: "type HMACKey struct {\n\t// The HMAC's secret key.\n\tSecret string\n\n\t// - AccessID is the ID of the HMAC key.\n\tAccessID string\n\n\t// Etag is the HTTP/1.1 - Entity tag.\n\tEtag string\n\n\t// ID is the ID of the HMAC key, including the - ProjectID and AccessID.\n\tID string\n\n\t// ProjectID is the ID of the project - that owns the\n\t// service account to which the key authenticates.\n\tProjectID - string\n\n\t// ServiceAccountEmail is the email address\n\t// of the key's associated - service account.\n\tServiceAccountEmail string\n\n\t// CreatedTime is the creation - time of the HMAC key.\n\tCreatedTime time.Time\n\n\t// UpdatedTime is the last - modification time of the HMAC key metadata.\n\tUpdatedTime time.Time\n\n\t// - State is the state of the HMAC key.\n\t// It can be one of StateActive, StateInactive - or StateDeleted.\n\tState HMACState\n}" + content: "type HMACKey struct {\n\t// The HMAC's secret key.\n\tSecret string\n\n\t// + AccessID is the ID of the HMAC key.\n\tAccessID string\n\n\t// + Etag is the HTTP/1.1 Entity tag.\n\tEtag string\n\n\t// + ID is the ID of the HMAC key, including the ProjectID and AccessID.\n\tID string\n\n\t// ProjectID is the + ID of the project that owns the\n\t// service account to which the key authenticates.\n\tProjectID + string\n\n\t// ServiceAccountEmail + is the email address\n\t// of the key's associated service account.\n\tServiceAccountEmail + string\n\n\t// CreatedTime + is the creation time of the HMAC key.\n\tCreatedTime time.Time\n\n\t// UpdatedTime is the last + modification time of the HMAC key metadata.\n\tUpdatedTime time.Time\n\n\t// State is the state of + the HMAC key.\n\t// It can be one of StateActive, StateInactive or StateDeleted.\n\tState + HMACState\n}" - uid: cloud.google.com/go/storage.HMACKeyAttrsToUpdate name: HMACKeyAttrsToUpdate id: HMACKeyAttrsToUpdate @@ -1410,8 +1450,8 @@ items: - go syntax: content: "type HMACKeyAttrsToUpdate struct {\n\t// State is required and must - be either StateActive or StateInactive.\n\tState HMACState\n\n\t// Etag is an - optional field and it is the HTTP/1.1 Entity tag.\n\tEtag string\n}" + be either StateActive or StateInactive.\n\tState HMACState\n\n\t// + Etag is an optional field and it is the HTTP/1.1 Entity tag.\n\tEtag string\n}" - uid: cloud.google.com/go/storage.HMACKeyHandle name: HMACKeyHandle id: HMACKeyHandle @@ -1630,7 +1670,7 @@ items: langs: - go syntax: - content: type HMACState string + content: type HMACState string - uid: cloud.google.com/go/storage.Active,Inactive,Deleted name: Active, Inactive, Deleted id: Active,Inactive,Deleted @@ -1640,12 +1680,13 @@ items: - go syntax: content: "const (\n\t// Active is the status for an active key that can be used - to sign\n\t// requests.\n\tActive HMACState = \"ACTIVE\"\n\n\t// Inactive is - the status for an inactive key thus requests signed by\n\t// this key will be - denied.\n\tInactive HMACState = \"INACTIVE\"\n\n\t// Deleted is the status for - a key that is deleted.\n\t// Once in this state the key cannot key cannot be - recovered\n\t// and does not count towards key limits. Deleted keys will be - cleaned\n\t// up later.\n\tDeleted HMACState = \"DELETED\"\n)" + to sign\n\t// requests.\n\tActive HMACState = \"ACTIVE\"\n\n\t// + Inactive is the status for an inactive key thus requests signed by\n\t// this + key will be denied.\n\tInactive HMACState = \"INACTIVE\"\n\n\t// + Deleted is the status for a key that is deleted.\n\t// Once in this state the + key cannot key cannot be recovered\n\t// and does not count towards key limits. + Deleted keys will be cleaned\n\t// up later.\n\tDeleted HMACState + = \"DELETED\"\n)" - uid: cloud.google.com/go/storage.Lifecycle name: Lifecycle id: Lifecycle @@ -1656,7 +1697,7 @@ items: langs: - go syntax: - content: "type Lifecycle struct {\n\tRules []LifecycleRule\n}" + content: "type Lifecycle struct {\n\tRules []LifecycleRule\n}" - uid: cloud.google.com/go/storage.LifecycleAction name: LifecycleAction id: LifecycleAction @@ -1670,9 +1711,9 @@ items: content: "type LifecycleAction struct {\n\t// Type is the type of action to take on matching objects.\n\t//\n\t// Acceptable values are \"Delete\" to delete matching objects and\n\t// \"SetStorageClass\" to set the storage class defined - in StorageClass on\n\t// matching objects.\n\tType string\n\n\t// StorageClass - is the storage class to set on matching objects if the Action\n\t// is \"SetStorageClass\".\n\tStorageClass - string\n}" + in StorageClass on\n\t// matching objects.\n\tType string\n\n\t// + StorageClass is the storage class to set on matching objects if the Action\n\t// + is \"SetStorageClass\".\n\tStorageClass string\n}" - uid: cloud.google.com/go/storage.LifecycleCondition name: LifecycleCondition id: LifecycleCondition @@ -1687,29 +1728,33 @@ items: - go syntax: content: "type LifecycleCondition struct {\n\t// AgeInDays is the age of the object - in days.\n\tAgeInDays int64\n\n\t// CreatedBefore is the time the object was - created.\n\t//\n\t// This condition is satisfied when an object is created before - midnight of\n\t// the specified date in UTC.\n\tCreatedBefore time.Time\n\n\t// - CustomTimeBefore is the CustomTime metadata field of the object. This\n\t// - condition is satisfied when an object's CustomTime timestamp is before\n\t// - midnight of the specified date in UTC.\n\t//\n\t// This condition can only be - satisfied if CustomTime has been set.\n\tCustomTimeBefore time.Time\n\n\t// + in days.\n\tAgeInDays int64\n\n\t// + CreatedBefore is the time the object was created.\n\t//\n\t// This condition + is satisfied when an object is created before midnight of\n\t// the specified + date in UTC.\n\tCreatedBefore time.Time\n\n\t// CustomTimeBefore is the + CustomTime metadata field of the object. This\n\t// condition is satisfied when + an object's CustomTime timestamp is before\n\t// midnight of the specified date + in UTC.\n\t//\n\t// This condition can only be satisfied if CustomTime has been + set.\n\tCustomTimeBefore time.Time\n\n\t// DaysSinceCustomTime is the days elapsed since the CustomTime date of the\n\t// object. This condition can only be satisfied if CustomTime has been set.\n\tDaysSinceCustomTime - int64\n\n\t// DaysSinceNoncurrentTime is the days elapsed since the noncurrent - timestamp\n\t// of the object. This condition is relevant only for versioned - objects.\n\tDaysSinceNoncurrentTime int64\n\n\t// Liveness specifies the object's - liveness. Relevant only for versioned objects\n\tLiveness Liveness\n\n\t// MatchesStorageClasses - is the condition matching the object's storage\n\t// class.\n\t//\n\t// Values - include \"STANDARD\", \"NEARLINE\", \"COLDLINE\" and \"ARCHIVE\".\n\tMatchesStorageClasses - []string\n\n\t// NoncurrentTimeBefore is the noncurrent timestamp of the object. - This\n\t// condition is satisfied when an object's noncurrent timestamp is before\n\t// - midnight of the specified date in UTC.\n\t//\n\t// This condition is relevant - only for versioned objects.\n\tNoncurrentTimeBefore time.Time\n\n\t// NumNewerVersions - is the condition matching objects with a number of newer versions.\n\t//\n\t// + int64\n\n\t// DaysSinceNoncurrentTime + is the days elapsed since the noncurrent timestamp\n\t// of the object. This + condition is relevant only for versioned objects.\n\tDaysSinceNoncurrentTime + int64\n\n\t// Liveness specifies + the object's liveness. Relevant only for versioned objects\n\tLiveness Liveness\n\n\t// + MatchesStorageClasses is the condition matching the object's storage\n\t// class.\n\t//\n\t// + Values include \"STANDARD\", \"NEARLINE\", \"COLDLINE\" and \"ARCHIVE\".\n\tMatchesStorageClasses + []string\n\n\t// NoncurrentTimeBefore + is the noncurrent timestamp of the object. This\n\t// condition is satisfied + when an object's noncurrent timestamp is before\n\t// midnight of the specified + date in UTC.\n\t//\n\t// This condition is relevant only for versioned objects.\n\tNoncurrentTimeBefore + time.Time\n\n\t// + NumNewerVersions is the condition matching objects with a number of newer versions.\n\t//\n\t// If the value is N, this condition is satisfied when there are at least N\n\t// versions (including the live version) newer than this version of the\n\t// object.\n\tNumNewerVersions - int64\n}" + int64\n}" - uid: cloud.google.com/go/storage.LifecycleRule name: LifecycleRule id: LifecycleRule @@ -1724,9 +1769,9 @@ items: - go syntax: content: "type LifecycleRule struct {\n\t// Action is the action to take when - all of the associated conditions are\n\t// met.\n\tAction LifecycleAction\n\n\t// + all of the associated conditions are\n\t// met.\n\tAction LifecycleAction\n\n\t// Condition is the set of conditions that must be met for the associated\n\t// - action to be taken.\n\tCondition LifecycleCondition\n}" + action to be taken.\n\tCondition LifecycleCondition\n}" - uid: cloud.google.com/go/storage.Liveness name: Liveness id: Liveness @@ -1737,7 +1782,7 @@ items: langs: - go syntax: - content: type Liveness int + content: type Liveness int - uid: cloud.google.com/go/storage.LiveAndArchived,Live,Archived name: LiveAndArchived, Live, Archived id: LiveAndArchived,Live,Archived @@ -1747,8 +1792,9 @@ items: - go syntax: content: "const (\n\t// LiveAndArchived includes both live and archived objects.\n\tLiveAndArchived - Liveness = iota\n\t// Live specifies that the object is still live.\n\tLive\n\t// - Archived specifies that the object is archived.\n\tArchived\n)" + Liveness = iota\n\t// + Live specifies that the object is still live.\n\tLive\n\t// Archived specifies + that the object is archived.\n\tArchived\n)" - uid: cloud.google.com/go/storage.Notification name: Notification id: Notification @@ -1760,17 +1806,20 @@ items: langs: - go syntax: - content: "type Notification struct {\n\t//The ID of the notification.\n\tID string\n\n\t// - The ID of the topic to which this subscription publishes.\n\tTopicID string\n\n\t// - The ID of the project to which the topic belongs.\n\tTopicProjectID string\n\n\t// + content: "type Notification struct {\n\t//The ID of the notification.\n\tID string\n\n\t// The ID of the + topic to which this subscription publishes.\n\tTopicID string\n\n\t// + The ID of the project to which the topic belongs.\n\tTopicProjectID string\n\n\t// Only send notifications about listed event types. If empty, send notifications\n\t// for all event types.\n\t// See https://cloud.google.com/storage/docs/pubsub-notifications#events.\n\tEventTypes - []string\n\n\t// If present, only apply this notification configuration to object - names that\n\t// begin with this prefix.\n\tObjectNamePrefix string\n\n\t// + []string\n\n\t// If present, + only apply this notification configuration to object names that\n\t// begin + with this prefix.\n\tObjectNamePrefix string\n\n\t// An optional list of additional attributes to attach to each Cloud PubSub\n\t// - message published for this notification subscription.\n\tCustomAttributes map[string]string\n\n\t// + message published for this notification subscription.\n\tCustomAttributes map[string]string\n\n\t// The contents of the message payload.\n\t// See https://cloud.google.com/storage/docs/pubsub-notifications#payload.\n\tPayloadFormat - string\n}" + string\n}" - uid: cloud.google.com/go/storage.ObjectAttrs name: ObjectAttrs id: ObjectAttrs @@ -1782,76 +1831,91 @@ items: - go syntax: content: "type ObjectAttrs struct {\n\t// Bucket is the name of the bucket containing - this GCS object.\n\t// This field is read-only.\n\tBucket string\n\n\t// Name - is the name of the object within the bucket.\n\t// This field is read-only.\n\tName - string\n\n\t// ContentType is the MIME type of the object's content.\n\tContentType - string\n\n\t// ContentLanguage is the content language of the object's content.\n\tContentLanguage - string\n\n\t// CacheControl is the Cache-Control header to be sent in the response\n\t// - headers when serving the object data.\n\tCacheControl string\n\n\t// EventBasedHold - specifies whether an object is under event-based hold. New\n\t// objects created - in a bucket whose DefaultEventBasedHold is set will\n\t// default to that value.\n\tEventBasedHold - bool\n\n\t// TemporaryHold specifies whether an object is under temporary hold. - While\n\t// this flag is set to true, the object is protected against deletion - and\n\t// overwrites.\n\tTemporaryHold bool\n\n\t// RetentionExpirationTime - is a server-determined value that specifies the\n\t// earliest time that the - object's retention period expires.\n\t// This is a read-only field.\n\tRetentionExpirationTime - time.Time\n\n\t// ACL is the list of access control rules for the object.\n\tACL - []ACLRule\n\n\t// If not empty, applies a predefined set of access controls. - It should be set\n\t// only when writing, copying or composing an object. When - copying or composing,\n\t// it acts as the destinationPredefinedAcl parameter.\n\t// - PredefinedACL is always empty for ObjectAttrs returned from the service.\n\t// - See https://cloud.google.com/storage/docs/json_api/v1/objects/insert\n\t// for - valid values.\n\tPredefinedACL string\n\n\t// Owner is the owner of the object. - This field is read-only.\n\t//\n\t// If non-zero, it is in the form of \"user-\".\n\tOwner - string\n\n\t// Size is the length of the object's content. This field is read-only.\n\tSize - int64\n\n\t// ContentEncoding is the encoding of the object's content.\n\tContentEncoding - string\n\n\t// ContentDisposition is the optional Content-Disposition header - of the object\n\t// sent in the response headers.\n\tContentDisposition string\n\n\t// + this GCS object.\n\t// This field is read-only.\n\tBucket string\n\n\t// + Name is the name of the object within the bucket.\n\t// This field is read-only.\n\tName + string\n\n\t// ContentType + is the MIME type of the object's content.\n\tContentType string\n\n\t// + ContentLanguage is the content language of the object's content.\n\tContentLanguage + string\n\n\t// CacheControl + is the Cache-Control header to be sent in the response\n\t// headers when serving + the object data.\n\tCacheControl string\n\n\t// + EventBasedHold specifies whether an object is under event-based hold. New\n\t// + objects created in a bucket whose DefaultEventBasedHold is set will\n\t// default + to that value.\n\tEventBasedHold bool\n\n\t// + TemporaryHold specifies whether an object is under temporary hold. While\n\t// + this flag is set to true, the object is protected against deletion and\n\t// + overwrites.\n\tTemporaryHold bool\n\n\t// + RetentionExpirationTime is a server-determined value that specifies the\n\t// + earliest time that the object's retention period expires.\n\t// This is a read-only + field.\n\tRetentionExpirationTime time.Time\n\n\t// ACL is the list of access + control rules for the object.\n\tACL []ACLRule\n\n\t// + If not empty, applies a predefined set of access controls. It should be set\n\t// + only when writing, copying or composing an object. When copying or composing,\n\t// + it acts as the destinationPredefinedAcl parameter.\n\t// PredefinedACL is always + empty for ObjectAttrs returned from the service.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/objects/insert\n\t// + for valid values.\n\tPredefinedACL string\n\n\t// + Owner is the owner of the object. This field is read-only.\n\t//\n\t// If non-zero, + it is in the form of \"user-\".\n\tOwner string\n\n\t// + Size is the length of the object's content. This field is read-only.\n\tSize + int64\n\n\t// ContentEncoding + is the encoding of the object's content.\n\tContentEncoding string\n\n\t// + ContentDisposition is the optional Content-Disposition header of the object\n\t// + sent in the response headers.\n\tContentDisposition string\n\n\t// MD5 is the MD5 hash of the object's content. This field is read-only,\n\t// except when used from a Writer. If set on a Writer, the uploaded\n\t// data - is rejected if its MD5 hash does not match this field.\n\tMD5 []byte\n\n\t// + is rejected if its MD5 hash does not match this field.\n\tMD5 []byte\n\n\t// CRC32C is the CRC32 checksum of the object's content using the Castagnoli93\n\t// polynomial. This field is read-only, except when used from a Writer or\n\t// Composer. In those cases, if the SendCRC32C field in the Writer or Composer\n\t// is set to is true, the uploaded data is rejected if its CRC32C hash does\n\t// - not match this field.\n\tCRC32C uint32\n\n\t// MediaLink is an URL to the object's - content. This field is read-only.\n\tMediaLink string\n\n\t// Metadata represents + not match this field.\n\tCRC32C uint32\n\n\t// + MediaLink is an URL to the object's content. This field is read-only.\n\tMediaLink + string\n\n\t// Metadata represents user-provided metadata, in key/value pairs.\n\t// It can be nil if no metadata - is provided.\n\tMetadata map[string]string\n\n\t// Generation is the generation - number of the object's content.\n\t// This field is read-only.\n\tGeneration - int64\n\n\t// Metageneration is the version of the metadata for this\n\t// object - at this generation. This field is used for preconditions\n\t// and for detecting - changes in metadata. A metageneration number\n\t// is only meaningful in the - context of a particular generation\n\t// of a particular object. This field - is read-only.\n\tMetageneration int64\n\n\t// StorageClass is the storage class - of the object. This defines\n\t// how objects are stored and determines the - SLA and the cost of storage.\n\t// Typical values are \"STANDARD\", \"NEARLINE\", - \"COLDLINE\" and \"ARCHIVE\".\n\t// Defaults to \"STANDARD\".\n\t// See https://cloud.google.com/storage/docs/storage-classes - for all\n\t// valid values.\n\tStorageClass string\n\n\t// Created is the time - the object was created. This field is read-only.\n\tCreated time.Time\n\n\t// + is provided.\n\tMetadata map[string]string\n\n\t// Generation is + the generation number of the object's content.\n\t// This field is read-only.\n\tGeneration + int64\n\n\t// Metageneration + is the version of the metadata for this\n\t// object at this generation. This + field is used for preconditions\n\t// and for detecting changes in metadata. + A metageneration number\n\t// is only meaningful in the context of a particular + generation\n\t// of a particular object. This field is read-only.\n\tMetageneration + int64\n\n\t// StorageClass + is the storage class of the object. This defines\n\t// how objects are stored + and determines the SLA and the cost of storage.\n\t// Typical values are \"STANDARD\", + \"NEARLINE\", \"COLDLINE\" and \"ARCHIVE\".\n\t// Defaults to \"STANDARD\".\n\t// + See https://cloud.google.com/storage/docs/storage-classes for all\n\t// valid + values.\n\tStorageClass string\n\n\t// + Created is the time the object was created. This field is read-only.\n\tCreated + time.Time\n\n\t// Deleted is the time the object was deleted.\n\t// If not deleted, it is the - zero value. This field is read-only.\n\tDeleted time.Time\n\n\t// Updated is - the creation or modification time of the object.\n\t// For buckets with versioning - enabled, changing an object's\n\t// metadata does not change this property. - This field is read-only.\n\tUpdated time.Time\n\n\t// CustomerKeySHA256 is the - base64-encoded SHA-256 hash of the\n\t// customer-supplied encryption key for - the object. It is empty if there is\n\t// no customer-supplied encryption key.\n\t// - See // https://cloud.google.com/storage/docs/encryption for more about\n\t// - encryption in Google Cloud Storage.\n\tCustomerKeySHA256 string\n\n\t// Cloud - KMS key name, in the form\n\t// projects/P/locations/L/keyRings/R/cryptoKeys/K, - used to encrypt this object,\n\t// if the object is encrypted by such a key.\n\t//\n\t// + zero value. This field is read-only.\n\tDeleted time.Time\n\n\t// Updated is the creation + or modification time of the object.\n\t// For buckets with versioning enabled, + changing an object's\n\t// metadata does not change this property. This field + is read-only.\n\tUpdated time.Time\n\n\t// + CustomerKeySHA256 is the base64-encoded SHA-256 hash of the\n\t// customer-supplied + encryption key for the object. It is empty if there is\n\t// no customer-supplied + encryption key.\n\t// See // https://cloud.google.com/storage/docs/encryption + for more about\n\t// encryption in Google Cloud Storage.\n\tCustomerKeySHA256 + string\n\n\t// Cloud KMS key + name, in the form\n\t// projects/P/locations/L/keyRings/R/cryptoKeys/K, used + to encrypt this object,\n\t// if the object is encrypted by such a key.\n\t//\n\t// Providing both a KMSKeyName and a customer-supplied encryption key (via\n\t// ObjectHandle.Key) will result in an error when writing an object.\n\tKMSKeyName - string\n\n\t// Prefix is set only for ObjectAttrs which represent synthetic - \"directory\n\t// entries\" when iterating over buckets using Query.Delimiter. - See\n\t// ObjectIterator.Next. When set, no other fields in ObjectAttrs will - be\n\t// populated.\n\tPrefix string\n\n\t// Etag is the HTTP/1.1 Entity tag - for the object.\n\t// This field is read-only.\n\tEtag string\n\n\t// A user-specified + string\n\n\t// Prefix is set + only for ObjectAttrs which represent synthetic \"directory\n\t// entries\" when + iterating over buckets using Query.Delimiter. See\n\t// ObjectIterator.Next. + When set, no other fields in ObjectAttrs will be\n\t// populated.\n\tPrefix + string\n\n\t// Etag is the + HTTP/1.1 Entity tag for the object.\n\t// This field is read-only.\n\tEtag string\n\n\t// A user-specified timestamp which can be applied to an object. This is\n\t// typically set in order to use the CustomTimeBefore and DaysSinceCustomTime\n\t// LifecycleConditions to manage object lifecycles.\n\t//\n\t// CustomTime cannot be removed once set on an object. It can be updated to a\n\t// later value but not to an earlier - one.\n\tCustomTime time.Time\n}" + one.\n\tCustomTime time.Time\n}" - uid: cloud.google.com/go/storage.ObjectAttrsToUpdate name: ObjectAttrsToUpdate id: ObjectAttrsToUpdate @@ -1872,14 +1936,26 @@ items: langs: - go syntax: - content: "type ObjectAttrsToUpdate struct {\n\tEventBasedHold optional.Bool\n\tTemporaryHold - \ optional.Bool\n\tContentType optional.String\n\tContentLanguage - \ optional.String\n\tContentEncoding optional.String\n\tContentDisposition - optional.String\n\tCacheControl optional.String\n\tCustomTime time.Time\n\tMetadata - \ map[string]string // set to map[string]string{} to delete\n\tACL - \ []ACLRule\n\n\t// If not empty, applies a predefined set of - access controls. ACL must be nil.\n\t// See https://cloud.google.com/storage/docs/json_api/v1/objects/patch.\n\tPredefinedACL - string\n}" + content: "type ObjectAttrsToUpdate struct {\n\tEventBasedHold optional.Bool\n\tTemporaryHold + \ optional.Bool\n\tContentType + \ optional.String\n\tContentLanguage + \ optional.String\n\tContentEncoding + \ optional.String\n\tContentDisposition + optional.String\n\tCacheControl + \ optional.String\n\tCustomTime + \ time.Time\n\tMetadata + \ map[string]string + // set to map[string]string{} to delete\n\tACL []ACLRule\n\n\t// + If not empty, applies a predefined set of access controls. ACL must be nil.\n\t// + See https://cloud.google.com/storage/docs/json_api/v1/objects/patch.\n\tPredefinedACL + string\n}" - uid: cloud.google.com/go/storage.ObjectHandle name: ObjectHandle id: ObjectHandle @@ -2326,21 +2402,24 @@ items: - go syntax: content: "type PolicyV4Fields struct {\n\t// ACL specifies the access control - permissions for the object.\n\t// Optional.\n\tACL string\n\t// CacheControl - specifies the caching directives for the object.\n\t// Optional.\n\tCacheControl - string\n\t// ContentType specifies the media type of the object.\n\t// Optional.\n\tContentType - string\n\t// ContentDisposition specifies how the file will be served back to - requesters.\n\t// Optional.\n\tContentDisposition string\n\t// ContentEncoding - specifies the decompressive transcoding that the object.\n\t// This field is - complementary to ContentType in that the file could be\n\t// compressed but - ContentType specifies the file's original media type.\n\t// Optional.\n\tContentEncoding - string\n\t// Metadata specifies custom metadata for the object.\n\t// If any - key doesn't begin with \"x-goog-meta-\", an error will be returned.\n\t// Optional.\n\tMetadata - map[string]string\n\t// StatusCodeOnSuccess when set, specifies the status code - that Cloud Storage\n\t// will serve back on successful upload of the object.\n\t// - Optional.\n\tStatusCodeOnSuccess int\n\t// RedirectToURLOnSuccess when set, - specifies the URL that Cloud Storage\n\t// will serve back on successful upload - of the object.\n\t// Optional.\n\tRedirectToURLOnSuccess string\n}" + permissions for the object.\n\t// Optional.\n\tACL string\n\t// + CacheControl specifies the caching directives for the object.\n\t// Optional.\n\tCacheControl + string\n\t// ContentType specifies + the media type of the object.\n\t// Optional.\n\tContentType string\n\t// + ContentDisposition specifies how the file will be served back to requesters.\n\t// + Optional.\n\tContentDisposition string\n\t// + ContentEncoding specifies the decompressive transcoding that the object.\n\t// + This field is complementary to ContentType in that the file could be\n\t// compressed + but ContentType specifies the file's original media type.\n\t// Optional.\n\tContentEncoding + string\n\t// Metadata specifies + custom metadata for the object.\n\t// If any key doesn't begin with \"x-goog-meta-\", + an error will be returned.\n\t// Optional.\n\tMetadata map[string]string\n\t// StatusCodeOnSuccess + when set, specifies the status code that Cloud Storage\n\t// will serve back + on successful upload of the object.\n\t// Optional.\n\tStatusCodeOnSuccess int\n\t// RedirectToURLOnSuccess + when set, specifies the URL that Cloud Storage\n\t// will serve back on successful + upload of the object.\n\t// Optional.\n\tRedirectToURLOnSuccess string\n}" - uid: cloud.google.com/go/storage.PostPolicyV4 name: PostPolicyV4 id: PostPolicyV4 @@ -2352,9 +2431,10 @@ items: - go syntax: content: "type PostPolicyV4 struct {\n\t// URL is the generated URL that the file - upload will be made to.\n\tURL string\n\t// Fields specifies the generated key-values - that the file uploader\n\t// must include in their multipart upload form.\n\tFields - map[string]string\n}" + upload will be made to.\n\tURL string\n\t// + Fields specifies the generated key-values that the file uploader\n\t// must + include in their multipart upload form.\n\tFields map[string]string\n}" - uid: cloud.google.com/go/storage.PostPolicyV4.GenerateSignedPostPolicyV4 name: | func GenerateSignedPostPolicyV4 @@ -2405,7 +2485,8 @@ items: langs: - go syntax: - content: "type PostPolicyV4Condition interface {\n\tjson.Marshaler\n\t// contains + content: "type PostPolicyV4Condition interface {\n\tjson.Marshaler\n\t// contains filtered or unexported methods\n}" - uid: cloud.google.com/go/storage.PostPolicyV4Condition.ConditionContentLengthRange name: | @@ -2451,37 +2532,41 @@ items: authorizer of the signed URL generation.\n\t// It is typically the Google service account client email address from\n\t// the Google Developers Console in the form of \"xxx@developer.gserviceaccount.com\".\n\t// Required.\n\tGoogleAccessID - string\n\n\t// PrivateKey is the Google service account private key. It is obtainable\n\t// - from the Google Developers Console.\n\t// At https://console.developers.google.com/project//apiui/credential,\n\t// + string\n\n\t// PrivateKey + is the Google service account private key. It is obtainable\n\t// from the Google + Developers Console.\n\t// At https://console.developers.google.com/project//apiui/credential,\n\t// create a service account client ID or reuse one of your existing service account\n\t// credentials. Click on the \"Generate new P12 key\" to generate and download\n\t// a new private key. Once you download the P12 file, use the following command\n\t// to convert it into a PEM file.\n\t//\n\t// $ openssl pkcs12 -in key.p12 -passin pass:notasecret -out key.pem -nodes\n\t//\n\t// Provide the contents of the PEM file as a byte slice.\n\t// Exactly one of PrivateKey or SignBytes must - be non-nil.\n\tPrivateKey []byte\n\n\t// SignBytes is a function for implementing - custom signing. For example, if\n\t// your application is running on Google - App Engine, you can use\n\t// appengine's internal signing function:\n\t// ctx - := appengine.NewContext(request)\n\t// acc, _ := appengine.ServiceAccount(ctx)\n\t// - \ url, err := SignedURL(\"bucket\", \"object\", &SignedURLOptions{\n\t// - \ \tGoogleAccessID: acc,\n\t// \tSignBytes: func(b []byte) ([]byte, error) - {\n\t// \t\t_, signedBytes, err := appengine.SignBytes(ctx, b)\n\t// \t\treturn - signedBytes, err\n\t// \t},\n\t// \t// etc.\n\t// })\n\t//\n\t// - Exactly one of PrivateKey or SignBytes must be non-nil.\n\tSignBytes func(hashBytes - []byte) (signature []byte, err error)\n\n\t// Expires is the expiration time - on the signed URL.\n\t// It must be a time in the future.\n\t// Required.\n\tExpires - time.Time\n\n\t// Style provides options for the type of URL to use. Options - are\n\t// PathStyle (default), BucketBoundHostname, and VirtualHostedStyle. - See\n\t// https://cloud.google.com/storage/docs/request-endpoints for details.\n\t// - Optional.\n\tStyle URLStyle\n\n\t// Insecure when set indicates that the generated - URL's scheme\n\t// will use \"http\" instead of \"https\" (default).\n\t// Optional.\n\tInsecure - bool\n\n\t// Fields specifies the attributes of a PostPolicyV4 request.\n\t// - When Fields is non-nil, its attributes must match those that will\n\t// passed - into field Conditions.\n\t// Optional.\n\tFields *PolicyV4Fields\n\n\t// The - conditions that the uploaded file will be expected to conform to.\n\t// When - used, the failure of an upload to satisfy a condition will result in\n\t// a - 4XX status code, back with the message describing the problem.\n\t// Optional.\n\tConditions - []PostPolicyV4Condition\n}" + be non-nil.\n\tPrivateKey []byte\n\n\t// + SignBytes is a function for implementing custom signing. For example, if\n\t// + your application is running on Google App Engine, you can use\n\t// appengine's + internal signing function:\n\t// ctx := appengine.NewContext(request)\n\t// + \ acc, _ := appengine.ServiceAccount(ctx)\n\t// url, err := SignedURL(\"bucket\", + \"object\", &SignedURLOptions{\n\t// \tGoogleAccessID: acc,\n\t// \tSignBytes: + func(b []byte) ([]byte, error) {\n\t// \t\t_, signedBytes, err := appengine.SignBytes(ctx, + b)\n\t// \t\treturn signedBytes, err\n\t// \t},\n\t// \t// etc.\n\t// + \ })\n\t//\n\t// Exactly one of PrivateKey or SignBytes must be non-nil.\n\tSignBytes + func(hashBytes []byte) (signature + []byte, err error)\n\n\t// + Expires is the expiration time on the signed URL.\n\t// It must be a time in + the future.\n\t// Required.\n\tExpires time.Time\n\n\t// Style provides options + for the type of URL to use. Options are\n\t// PathStyle (default), BucketBoundHostname, + and VirtualHostedStyle. See\n\t// https://cloud.google.com/storage/docs/request-endpoints + for details.\n\t// Optional.\n\tStyle URLStyle\n\n\t// + Insecure when set indicates that the generated URL's scheme\n\t// will use \"http\" + instead of \"https\" (default).\n\t// Optional.\n\tInsecure bool\n\n\t// + Fields specifies the attributes of a PostPolicyV4 request.\n\t// When Fields + is non-nil, its attributes must match those that will\n\t// passed into field + Conditions.\n\t// Optional.\n\tFields *PolicyV4Fields\n\n\t// + The conditions that the uploaded file will be expected to conform to.\n\t// + When used, the failure of an upload to satisfy a condition will result in\n\t// + a 4XX status code, back with the message describing the problem.\n\t// Optional.\n\tConditions + []PostPolicyV4Condition\n}" - uid: cloud.google.com/go/storage.ProjectTeam name: ProjectTeam id: ProjectTeam @@ -2492,7 +2577,8 @@ items: langs: - go syntax: - content: "type ProjectTeam struct {\n\tProjectNumber string\n\tTeam string\n}" + content: "type ProjectTeam struct {\n\tProjectNumber string\n\tTeam + \ string\n}" - uid: cloud.google.com/go/storage.Query name: Query id: Query @@ -2508,16 +2594,18 @@ items: prefix, do not contain delimiter. Objects whose names,\n\t// aside from the prefix, contain delimiter will have their name,\n\t// truncated after the delimiter, returned in prefixes.\n\t// Duplicate prefixes are omitted.\n\t// Optional.\n\tDelimiter - string\n\n\t// Prefix is the prefix filter to query objects\n\t// whose names - begin with this prefix.\n\t// Optional.\n\tPrefix string\n\n\t// Versions indicates - whether multiple versions of the same\n\t// object will be included in the results.\n\tVersions - bool\n\n\t// StartOffset is used to filter results to objects whose names are\n\t// - lexicographically equal to or after startOffset. If endOffset is also set,\n\t// - the objects listed will have names between startOffset (inclusive) and\n\t// - endOffset (exclusive).\n\tStartOffset string\n\n\t// EndOffset is used to filter - results to objects whose names are\n\t// lexicographically before endOffset. - If startOffset is also set, the objects\n\t// listed will have names between - startOffset (inclusive) and endOffset (exclusive).\n\tEndOffset string\n\t// + string\n\n\t// Prefix is the + prefix filter to query objects\n\t// whose names begin with this prefix.\n\t// + Optional.\n\tPrefix string\n\n\t// + Versions indicates whether multiple versions of the same\n\t// object will be + included in the results.\n\tVersions bool\n\n\t// + StartOffset is used to filter results to objects whose names are\n\t// lexicographically + equal to or after startOffset. If endOffset is also set,\n\t// the objects listed + will have names between startOffset (inclusive) and\n\t// endOffset (exclusive).\n\tStartOffset + string\n\n\t// EndOffset is + used to filter results to objects whose names are\n\t// lexicographically before + endOffset. If startOffset is also set, the objects\n\t// listed will have names + between startOffset (inclusive) and endOffset (exclusive).\n\tEndOffset string\n\t// contains filtered or unexported fields\n}" - uid: cloud.google.com/go/storage.Query.SetAttrSelection name: | @@ -2553,8 +2641,8 @@ items: langs: - go syntax: - content: "type Reader struct {\n\tAttrs ReaderObjectAttrs\n\t// contains filtered - or unexported fields\n}" + content: "type Reader struct {\n\tAttrs ReaderObjectAttrs\n\t// + contains filtered or unexported fields\n}" - uid: cloud.google.com/go/storage.Reader.CacheControl name: | func (*Reader) CacheControl @@ -2678,18 +2766,22 @@ items: - go syntax: content: "type ReaderObjectAttrs struct {\n\t// Size is the length of the object's - content.\n\tSize int64\n\n\t// StartOffset is the byte offset within the object\n\t// - from which reading begins.\n\t// This value is only non-zero for range requests.\n\tStartOffset - int64\n\n\t// ContentType is the MIME type of the object's content.\n\tContentType - string\n\n\t// ContentEncoding is the encoding of the object's content.\n\tContentEncoding - string\n\n\t// CacheControl specifies whether and for how long browser and Internet\n\t// - caches are allowed to cache your objects.\n\tCacheControl string\n\n\t// LastModified - is the time that the object was last modified.\n\tLastModified time.Time\n\n\t// - Generation is the generation number of the object's content.\n\tGeneration int64\n\n\t// - Metageneration is the version of the metadata for this object at\n\t// this - generation. This field is used for preconditions and for\n\t// detecting changes - in metadata. A metageneration number is only\n\t// meaningful in the context - of a particular generation of a\n\t// particular object.\n\tMetageneration int64\n}" + content.\n\tSize int64\n\n\t// + StartOffset is the byte offset within the object\n\t// from which reading begins.\n\t// + This value is only non-zero for range requests.\n\tStartOffset int64\n\n\t// + ContentType is the MIME type of the object's content.\n\tContentType string\n\n\t// + ContentEncoding is the encoding of the object's content.\n\tContentEncoding + string\n\n\t// CacheControl + specifies whether and for how long browser and Internet\n\t// caches are allowed + to cache your objects.\n\tCacheControl string\n\n\t// + LastModified is the time that the object was last modified.\n\tLastModified + time.Time\n\n\t// + Generation is the generation number of the object's content.\n\tGeneration int64\n\n\t// Metageneration is + the version of the metadata for this object at\n\t// this generation. This field + is used for preconditions and for\n\t// detecting changes in metadata. A metageneration + number is only\n\t// meaningful in the context of a particular generation of + a\n\t// particular object.\n\tMetageneration int64\n}" - uid: cloud.google.com/go/storage.RetentionPolicy name: RetentionPolicy id: RetentionPolicy @@ -2715,11 +2807,13 @@ items: that objects need to be\n\t// retained. Retention duration must be greater than zero and less than\n\t// 100 years. Note that enforcement of retention periods less than a day\n\t// is not guaranteed. Such periods should only be used for - testing\n\t// purposes.\n\tRetentionPeriod time.Duration\n\n\t// EffectiveTime + testing\n\t// purposes.\n\tRetentionPeriod time.Duration\n\n\t// EffectiveTime is the time from which the policy was enforced and\n\t// effective. This field - is read-only.\n\tEffectiveTime time.Time\n\n\t// IsLocked describes whether + is read-only.\n\tEffectiveTime time.Time\n\n\t// IsLocked describes whether the bucket is locked. Once locked, an\n\t// object retention policy cannot be - modified.\n\t// This field is read-only.\n\tIsLocked bool\n}" + modified.\n\t// This field is read-only.\n\tIsLocked bool\n}" - uid: cloud.google.com/go/storage.SignedURLOptions name: SignedURLOptions id: SignedURLOptions @@ -2733,47 +2827,54 @@ items: content: "type SignedURLOptions struct {\n\t// GoogleAccessID represents the authorizer of the signed URL generation.\n\t// It is typically the Google service account client email address from\n\t// the Google Developers Console in the form of - \"xxx@developer.gserviceaccount.com\".\n\t// Required.\n\tGoogleAccessID string\n\n\t// - PrivateKey is the Google service account private key. It is obtainable\n\t// - from the Google Developers Console.\n\t// At https://console.developers.google.com/project//apiui/credential,\n\t// + \"xxx@developer.gserviceaccount.com\".\n\t// Required.\n\tGoogleAccessID string\n\n\t// PrivateKey is + the Google service account private key. It is obtainable\n\t// from the Google + Developers Console.\n\t// At https://console.developers.google.com/project//apiui/credential,\n\t// create a service account client ID or reuse one of your existing service account\n\t// credentials. Click on the \"Generate new P12 key\" to generate and download\n\t// a new private key. Once you download the P12 file, use the following command\n\t// to convert it into a PEM file.\n\t//\n\t// $ openssl pkcs12 -in key.p12 -passin pass:notasecret -out key.pem -nodes\n\t//\n\t// Provide the contents of the PEM file as a byte slice.\n\t// Exactly one of PrivateKey or SignBytes must - be non-nil.\n\tPrivateKey []byte\n\n\t// SignBytes is a function for implementing - custom signing. For example, if\n\t// your application is running on Google - App Engine, you can use\n\t// appengine's internal signing function:\n\t// ctx - := appengine.NewContext(request)\n\t// acc, _ := appengine.ServiceAccount(ctx)\n\t// - \ url, err := SignedURL(\"bucket\", \"object\", &SignedURLOptions{\n\t// - \ \tGoogleAccessID: acc,\n\t// \tSignBytes: func(b []byte) ([]byte, error) - {\n\t// \t\t_, signedBytes, err := appengine.SignBytes(ctx, b)\n\t// \t\treturn - signedBytes, err\n\t// \t},\n\t// \t// etc.\n\t// })\n\t//\n\t// - Exactly one of PrivateKey or SignBytes must be non-nil.\n\tSignBytes func([]byte) - ([]byte, error)\n\n\t// Method is the HTTP method to be used with the signed - URL.\n\t// Signed URLs can be used with GET, HEAD, PUT, and DELETE requests.\n\t// - Required.\n\tMethod string\n\n\t// Expires is the expiration time on the signed - URL. It must be\n\t// a datetime in the future. For SigningSchemeV4, the expiration - may be no\n\t// more than seven days in the future.\n\t// Required.\n\tExpires - time.Time\n\n\t// ContentType is the content type header the client must provide\n\t// - to use the generated signed URL.\n\t// Optional.\n\tContentType string\n\n\t// + be non-nil.\n\tPrivateKey []byte\n\n\t// + SignBytes is a function for implementing custom signing. For example, if\n\t// + your application is running on Google App Engine, you can use\n\t// appengine's + internal signing function:\n\t// ctx := appengine.NewContext(request)\n\t// + \ acc, _ := appengine.ServiceAccount(ctx)\n\t// url, err := SignedURL(\"bucket\", + \"object\", &SignedURLOptions{\n\t// \tGoogleAccessID: acc,\n\t// \tSignBytes: + func(b []byte) ([]byte, error) {\n\t// \t\t_, signedBytes, err := appengine.SignBytes(ctx, + b)\n\t// \t\treturn signedBytes, err\n\t// \t},\n\t// \t// etc.\n\t// + \ })\n\t//\n\t// Exactly one of PrivateKey or SignBytes must be non-nil.\n\tSignBytes + func([]byte) ([]byte, + error)\n\n\t// Method is the + HTTP method to be used with the signed URL.\n\t// Signed URLs can be used with + GET, HEAD, PUT, and DELETE requests.\n\t// Required.\n\tMethod string\n\n\t// + Expires is the expiration time on the signed URL. It must be\n\t// a datetime + in the future. For SigningSchemeV4, the expiration may be no\n\t// more than + seven days in the future.\n\t// Required.\n\tExpires time.Time\n\n\t// ContentType is the content + type header the client must provide\n\t// to use the generated signed URL.\n\t// + Optional.\n\tContentType string\n\n\t// Headers is a list of extension headers the client must provide\n\t// in order to use the generated signed URL. Each must be a string of the\n\t// form \"key:values\", - with multiple values separated by a semicolon.\n\t// Optional.\n\tHeaders []string\n\n\t// - QueryParameters is a map of additional query parameters. When\n\t// SigningScheme - is V4, this is used in computing the signature, and the\n\t// client must use - the same query parameters when using the generated signed\n\t// URL.\n\t// Optional.\n\tQueryParameters - url.Values\n\n\t// MD5 is the base64 encoded MD5 checksum of the file.\n\t// - If provided, the client should provide the exact value on the request\n\t// - header in order to use the signed URL.\n\t// Optional.\n\tMD5 string\n\n\t// + with multiple values separated by a semicolon.\n\t// Optional.\n\tHeaders []string\n\n\t// QueryParameters + is a map of additional query parameters. When\n\t// SigningScheme is V4, this + is used in computing the signature, and the\n\t// client must use the same query + parameters when using the generated signed\n\t// URL.\n\t// Optional.\n\tQueryParameters + url.Values\n\n\t// + MD5 is the base64 encoded MD5 checksum of the file.\n\t// If provided, the client + should provide the exact value on the request\n\t// header in order to use the + signed URL.\n\t// Optional.\n\tMD5 string\n\n\t// Style provides options for the type of URL to use. Options are\n\t// PathStyle (default), BucketBoundHostname, and VirtualHostedStyle. See\n\t// https://cloud.google.com/storage/docs/request-endpoints - for details.\n\t// Only supported for V4 signing.\n\t// Optional.\n\tStyle URLStyle\n\n\t// - Insecure determines whether the signed URL should use HTTPS (default) or\n\t// - HTTP.\n\t// Only supported for V4 signing.\n\t// Optional.\n\tInsecure bool\n\n\t// + for details.\n\t// Only supported for V4 signing.\n\t// Optional.\n\tStyle URLStyle\n\n\t// Insecure determines whether the signed + URL should use HTTPS (default) or\n\t// HTTP.\n\t// Only supported for V4 signing.\n\t// + Optional.\n\tInsecure bool\n\n\t// Scheme determines the version of URL signing to use. Default is\n\t// SigningSchemeV2.\n\tScheme - SigningScheme\n}" + SigningScheme\n}" - uid: cloud.google.com/go/storage.SigningScheme name: SigningScheme id: SigningScheme @@ -2784,7 +2885,7 @@ items: langs: - go syntax: - content: type SigningScheme int + content: type SigningScheme int - uid: cloud.google.com/go/storage.SigningSchemeDefault,SigningSchemeV2,SigningSchemeV4 name: SigningSchemeDefault, SigningSchemeV2, SigningSchemeV4 id: SigningSchemeDefault,SigningSchemeV2,SigningSchemeV4 @@ -2794,7 +2895,8 @@ items: - go syntax: content: "const (\n\t// SigningSchemeDefault is presently V2 and will change to - V4 in the future.\n\tSigningSchemeDefault SigningScheme = iota\n\n\t// SigningSchemeV2 + V4 in the future.\n\tSigningSchemeDefault SigningScheme + = iota\n\n\t// SigningSchemeV2 uses the V2 scheme to sign URLs.\n\tSigningSchemeV2\n\n\t// SigningSchemeV4 uses the V4 scheme to sign URLs.\n\tSigningSchemeV4\n)" - uid: cloud.google.com/go/storage.URLStyle @@ -2869,8 +2971,9 @@ items: syntax: content: "type UniformBucketLevelAccess struct {\n\t// Enabled specifies whether access checks use only bucket-level IAM\n\t// policies. Enabled may be disabled - until the locked time.\n\tEnabled bool\n\t// LockedTime specifies the deadline - for changing Enabled from true to\n\t// false.\n\tLockedTime time.Time\n}" + until the locked time.\n\tEnabled bool\n\t// + LockedTime specifies the deadline for changing Enabled from true to\n\t// false.\n\tLockedTime + time.Time\n}" - uid: cloud.google.com/go/storage.Writer name: Writer id: Writer @@ -2883,34 +2986,34 @@ items: syntax: content: "type Writer struct {\n\t// ObjectAttrs are optional attributes to set on the object. Any attributes\n\t// must be initialized before the first Write - call. Nil or zero-valued\n\t// attributes are ignored.\n\tObjectAttrs\n\n\t// + call. Nil or zero-valued\n\t// attributes are ignored.\n\tObjectAttrs\n\n\t// SendCRC specifies whether to transmit a CRC32C field. It should be set\n\t// to true in addition to setting the Writer's CRC32C field, because zero\n\t// is a valid CRC and normally a zero would not be transmitted.\n\t// If a CRC32C is sent, and the data written does not match the checksum,\n\t// the write will - be rejected.\n\tSendCRC32C bool\n\n\t// ChunkSize controls the maximum number - of bytes of the object that the\n\t// Writer will attempt to send to the server - in a single request. Objects\n\t// smaller than the size will be sent in a single - request, while larger\n\t// objects will be split over multiple requests. The - size will be rounded up\n\t// to the nearest multiple of 256K.\n\t//\n\t// ChunkSize - will default to a reasonable value. If you perform many\n\t// concurrent writes - of small objects (under ~8MB), you may wish set ChunkSize\n\t// to a value that - matches your objects' sizes to avoid consuming large\n\t// amounts of memory. - See\n\t// https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload#size\n\t// + be rejected.\n\tSendCRC32C bool\n\n\t// + ChunkSize controls the maximum number of bytes of the object that the\n\t// + Writer will attempt to send to the server in a single request. Objects\n\t// + smaller than the size will be sent in a single request, while larger\n\t// objects + will be split over multiple requests. The size will be rounded up\n\t// to the + nearest multiple of 256K.\n\t//\n\t// ChunkSize will default to a reasonable + value. If you perform many\n\t// concurrent writes of small objects (under ~8MB), + you may wish set ChunkSize\n\t// to a value that matches your objects' sizes + to avoid consuming large\n\t// amounts of memory. See\n\t// https://cloud.google.com/storage/docs/json_api/v1/how-tos/upload#size\n\t// for more information about performance trade-offs related to ChunkSize.\n\t//\n\t// If ChunkSize is set to zero, chunking will be disabled and the object will\n\t// be uploaded in a single request without the use of a buffer. This will\n\t// further reduce memory used during uploads, but will also prevent the writer\n\t// from retrying in case of a transient error from the server, since a buffer\n\t// is required in order to retry the failed request.\n\t//\n\t// ChunkSize must - be set before the first Write call.\n\tChunkSize int\n\n\t// ProgressFunc can - be used to monitor the progress of a large write.\n\t// operation. If ProgressFunc - is not nil and writing requires multiple\n\t// calls to the underlying service - (see\n\t// https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload),\n\t// + be set before the first Write call.\n\tChunkSize int\n\n\t// + ProgressFunc can be used to monitor the progress of a large write.\n\t// operation. + If ProgressFunc is not nil and writing requires multiple\n\t// calls to the + underlying service (see\n\t// https://cloud.google.com/storage/docs/json_api/v1/how-tos/resumable-upload),\n\t// then ProgressFunc will be invoked after each call with the number of bytes of\n\t// content copied so far.\n\t//\n\t// ProgressFunc should return quickly without - blocking.\n\tProgressFunc func(int64)\n\t// contains filtered or unexported - fields\n}" + blocking.\n\tProgressFunc func(int64)\n\t// + contains filtered or unexported fields\n}" - uid: cloud.google.com/go/storage.Writer.Attrs name: | func (*Writer) Attrs diff --git a/third_party/pkgsite/print_type.go b/third_party/pkgsite/print_type.go index 64b6c90170e..1bb39b2129b 100644 --- a/third_party/pkgsite/print_type.go +++ b/third_party/pkgsite/print_type.go @@ -17,21 +17,86 @@ import ( "bytes" "fmt" "go/ast" + "go/doc" "go/printer" + "go/scanner" "go/token" "strconv" "strings" ) // PrintType returns a string representation of the decl. -func PrintType(fset *token.FileSet, decl ast.Decl) string { +// +// PrintType works by: +// 1. Generate a map from every identifier to a URL for the identifier (or no +// URL if the identifier shouldn't link). +// 2. ast.Inspect the decl to get an ordered slice of every identifier to the +// link for it, using the map from step 1. +// 3. Print out the plain doc for the decl. +// 4. Use scanner.Scanner to find every identifier (in the same order as step +// 2). If there is a link for the identifier, insert it. Otherwise, print +// the plain doc. +func PrintType(fset *token.FileSet, decl ast.Decl, toURL func(string, string) string) string { + anchorLinksMap := generateAnchorLinks(decl, toURL) + // Convert the map (keyed by *ast.Ident) to a slice of URLs (or no URL). + // + // This relies on the ast.Inspect and scanner.Scanner both + // visiting *ast.Ident and token.IDENT nodes in the same order. + var anchorLinks []string + ast.Inspect(decl, func(node ast.Node) bool { + if id, ok := node.(*ast.Ident); ok { + anchorLinks = append(anchorLinks, anchorLinksMap[id]) + } + return true + }) + v := &declVisitor{} ast.Walk(v, decl) var b bytes.Buffer p := printer.Config{Mode: printer.UseSpaces | printer.TabIndent, Tabwidth: 4} p.Fprint(&b, fset, &printer.CommentedNode{Node: decl, Comments: v.Comments}) - return b.String() + src := b.Bytes() + var out strings.Builder + + fakeFset := token.NewFileSet() + file := fakeFset.AddFile("", fakeFset.Base(), b.Len()) + + var lastOffset int // last src offset copied to output buffer + var s scanner.Scanner + s.Init(file, src, nil, scanner.ScanComments) + identIdx := 0 +scan: + for { + p, tok, lit := s.Scan() + line := file.Line(p) - 1 // current 0-indexed line number + offset := file.Offset(p) // current offset into source file + + // Add traversed bytes from src to the appropriate line. + prevLines := strings.SplitAfter(string(src[lastOffset:offset]), "\n") + for i, ln := range prevLines { + n := line - len(prevLines) + i + 1 + if n < 0 { // possible at EOF + n = 0 + } + out.WriteString(ln) + } + + lastOffset = offset + switch tok { + case token.EOF: + break scan + case token.IDENT: + if identIdx < len(anchorLinks) && anchorLinks[identIdx] != "" { + fmt.Fprintf(&out, `%s`, anchorLinks[identIdx], lit) + } else { + out.WriteString(lit) + } + identIdx++ + lastOffset += len(lit) + } + } + return out.String() } // declVisitor is used to walk over the AST and trim large string @@ -81,3 +146,53 @@ func stringBasicLitSize(s string) string { } return fmt.Sprintf("/* %d byte string literal not displayed */", len(u)) } + +// generateAnchorLinks returns a mapping of *ast.Ident objects to the URL +// that the identifier should link to. +func generateAnchorLinks(decl ast.Decl, toURL func(string, string) string) map[*ast.Ident]string { + m := map[*ast.Ident]string{} + ignore := map[ast.Node]bool{} + ast.Inspect(decl, func(node ast.Node) bool { + if ignore[node] { + return false + } + switch node := node.(type) { + case *ast.SelectorExpr: + // Package qualified identifier (e.g., "io.EOF"). + if prefix, _ := node.X.(*ast.Ident); prefix != nil { + if obj := prefix.Obj; obj != nil && obj.Kind == ast.Pkg { + if spec, _ := obj.Decl.(*ast.ImportSpec); spec != nil { + if path, err := strconv.Unquote(spec.Path.Value); err == nil { + // Register two links, one for the package + // and one for the qualified identifier. + m[prefix] = toURL(path, "") + m[node.Sel] = toURL(path, node.Sel.Name) + return false + } + } + } + } + case *ast.Ident: + if node.Obj == nil && doc.IsPredeclared(node.Name) { + m[node] = toURL("builtin", node.Name) + } else if node.Obj != nil && node.Obj.Kind != ast.Var { + // TODO: && topLevelDecls[node.Obj.Decl] + m[node] = toURL("", node.Name) + } + case *ast.FuncDecl: + ignore[node.Name] = true // E.g., "func NoLink() int" + case *ast.TypeSpec: + ignore[node.Name] = true // E.g., "type NoLink int" + case *ast.ValueSpec: + for _, n := range node.Names { + ignore[n] = true // E.g., "var NoLink1, NoLink2 int" + } + case *ast.AssignStmt: + for _, n := range node.Lhs { + ignore[n] = true // E.g., "NoLink1, NoLink2 := 0, 1" + } + } + return true + }) + return m +}