From 235714a11faea5f84309e5deaaa8f265c00f8400 Mon Sep 17 00:00:00 2001 From: Tyler Bui-Palsulich Date: Thu, 17 Sep 2020 10:03:08 -0400 Subject: [PATCH 1/3] feat(docfx): add support for examples Examples are located in _test.go files, which go/packages parses into a separate foo_test package. So, this requires an extra step of collecting all files from the package, including test packages, then parsing them. That way, the go/doc package can associate types/functions/packages with the examples for them (rather than an unassociated list). --- internal/godocfx/parse.go | 165 ++++++++++++++------- internal/godocfx/testdata/golden/index.yml | 99 +++++++++++++ 2 files changed, 214 insertions(+), 50 deletions(-) diff --git a/internal/godocfx/parse.go b/internal/godocfx/parse.go index ea502777210..42d69a541d8 100644 --- a/internal/godocfx/parse.go +++ b/internal/godocfx/parse.go @@ -17,9 +17,14 @@ package main import ( + "bytes" "fmt" "go/ast" "go/doc" + "go/format" + "go/parser" + "go/printer" + "go/token" "log" "sort" "strings" @@ -58,17 +63,23 @@ type syntax struct { Content string `yaml:"content,omitempty"` } +type example struct { + Content string `yaml:"content,omitempty"` + Name string `yaml:"name,omitempty"` +} + // item represents a DocFX item. type item struct { - UID string `yaml:"uid"` - Name string `yaml:"name,omitempty"` - ID string `yaml:"id,omitempty"` - Summary string `yaml:"summary,omitempty"` - Parent string `yaml:"parent,omitempty"` - Type string `yaml:"type,omitempty"` - Langs []string `yaml:"langs,omitempty"` - Syntax syntax `yaml:"syntax,omitempty"` - Children []child `yaml:"children,omitempty"` + UID string `yaml:"uid"` + Name string `yaml:"name,omitempty"` + ID string `yaml:"id,omitempty"` + Summary string `yaml:"summary,omitempty"` + Parent string `yaml:"parent,omitempty"` + Type string `yaml:"type,omitempty"` + Langs []string `yaml:"langs,omitempty"` + Syntax syntax `yaml:"syntax,omitempty"` + Example []example `yaml:"example,omitempty"` + Children []child `yaml:"children,omitempty"` } func (p *page) addItem(i *item) { @@ -109,97 +120,116 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er log.Printf("Processing %s@%s", module.Path, module.Version) + // First, collect all of the files grouped by package, including test + // packages. + pkgFiles := map[string][]string{} for _, pkg := range pkgs { - if pkg == nil || pkg.Module == nil { + id := pkg.ID + // See https://pkg.go.dev/golang.org/x/tools/go/packages#Config. + // The uncompiled test package shows up as "foo_test [foo.test]". + if strings.HasSuffix(id, ".test") || + strings.Contains(id, "internal") || + (strings.Contains(id, " [") && !strings.Contains(id, "_test [")) { continue } - if pkg.Module.Path != module.Path { - skippedModules[pkg.Module.Path] = struct{}{} - continue + if strings.Contains(id, "_test") { + id = id[0:strings.Index(id, "_test [")] + } else { + // The test package doesn't have Module set. + if pkg.Module.Path != module.Path { + skippedModules[pkg.Module.Path] = struct{}{} + continue + } } - // Don't generate docs for tests or internal. - switch { - case strings.HasSuffix(pkg.ID, ".test"), - strings.HasSuffix(pkg.ID, ".test]"), - strings.Contains(pkg.ID, "internal"): - continue + for _, f := range pkg.Syntax { + name := pkg.Fset.File(f.Pos()).Name() + if strings.HasSuffix(name, ".go") { + pkgFiles[id] = append(pkgFiles[id], name) + } } + } - // Collect all .go files. - files := []*ast.File{} - for _, f := range pkg.Syntax { - tf := pkg.Fset.File(f.Pos()) - if strings.HasSuffix(tf.Name(), ".go") { - files = append(files, f) + // Once the files are grouped by package, process each package + // independently. + for pkgPath, files := range pkgFiles { + parsedFiles := []*ast.File{} + fset := token.NewFileSet() + for _, f := range files { + pf, err := parser.ParseFile(fset, f, nil, parser.ParseComments) + if err != nil { + return nil, nil, nil, fmt.Errorf("ParseFile: %v", err) } + parsedFiles = append(parsedFiles, pf) } // Parse out GoDoc. - docPkg, err := doc.NewFromFiles(pkg.Fset, files, pkg.PkgPath) + docPkg, err := doc.NewFromFiles(fset, parsedFiles, pkgPath) if err != nil { return nil, nil, nil, fmt.Errorf("doc.NewFromFiles: %v", err) } toc = append(toc, &tocItem{ - UID: pkg.ID, - Name: pkg.PkgPath, + UID: docPkg.ImportPath, + Name: docPkg.ImportPath, }) pkgItem := &item{ - UID: pkg.ID, - Name: pkg.PkgPath, - ID: pkg.Name, + UID: docPkg.ImportPath, + Name: docPkg.ImportPath, + ID: docPkg.Name, Summary: docPkg.Doc, Langs: onlyGo, Type: "package", + Example: processExamples(docPkg.Examples, fset), } pkgPage := &page{Items: []*item{pkgItem}} - pages[pkg.PkgPath] = pkgPage + pages[pkgPath] = pkgPage for _, c := range docPkg.Consts { name := strings.Join(c.Names, ", ") id := strings.Join(c.Names, ",") - uid := pkg.PkgPath + "." + id + uid := docPkg.ImportPath + "." + id pkgItem.addChild(child(uid)) pkgPage.addItem(&item{ UID: uid, Name: name, ID: id, - Parent: pkg.PkgPath, + Parent: docPkg.ImportPath, Type: "const", Summary: c.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(pkg.Fset, c.Decl)}, + Syntax: syntax{Content: pkgsite.PrintType(fset, c.Decl)}, }) } for _, v := range docPkg.Vars { name := strings.Join(v.Names, ", ") id := strings.Join(v.Names, ",") - uid := pkg.PkgPath + "." + id + uid := docPkg.ImportPath + "." + id pkgItem.addChild(child(uid)) pkgPage.addItem(&item{ UID: uid, Name: name, ID: id, - Parent: pkg.PkgPath, + Parent: docPkg.ImportPath, Type: "variable", Summary: v.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(pkg.Fset, v.Decl)}, + Syntax: syntax{Content: pkgsite.PrintType(fset, v.Decl)}, }) } for _, t := range docPkg.Types { - uid := pkg.PkgPath + "." + t.Name + uid := docPkg.ImportPath + "." + t.Name pkgItem.addChild(child(uid)) typeItem := &item{ UID: uid, Name: t.Name, ID: t.Name, - Parent: pkg.PkgPath, + Parent: docPkg.ImportPath, Type: "type", Summary: t.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(pkg.Fset, t.Decl)}, + Syntax: syntax{Content: pkgsite.PrintType(fset, t.Decl)}, + Example: processExamples(t.Examples, fset), } // TODO: items are added as page.Children, rather than // typeItem.Children, as a workaround for the DocFX template. @@ -208,7 +238,7 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er for _, c := range t.Consts { name := strings.Join(c.Names, ", ") id := strings.Join(c.Names, ",") - cUID := pkg.PkgPath + "." + id + cUID := docPkg.ImportPath + "." + id pkgItem.addChild(child(cUID)) pkgPage.addItem(&item{ UID: cUID, @@ -218,13 +248,13 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er Type: "const", Summary: c.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(pkg.Fset, c.Decl)}, + Syntax: syntax{Content: pkgsite.PrintType(fset, c.Decl)}, }) } for _, v := range t.Vars { name := strings.Join(v.Names, ", ") id := strings.Join(v.Names, ",") - cUID := pkg.PkgPath + "." + id + cUID := docPkg.ImportPath + "." + id pkgItem.addChild(child(cUID)) pkgPage.addItem(&item{ UID: cUID, @@ -234,7 +264,7 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er Type: "variable", Summary: v.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(pkg.Fset, v.Decl)}, + Syntax: syntax{Content: pkgsite.PrintType(fset, v.Decl)}, }) } @@ -249,7 +279,8 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er Type: "function", Summary: fn.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.Synopsis(pkg.Fset, fn.Decl)}, + Syntax: syntax{Content: pkgsite.Synopsis(fset, fn.Decl)}, + Example: processExamples(fn.Examples, fset), }) } for _, fn := range t.Methods { @@ -263,22 +294,24 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er Type: "function", // Note: this is actually a method. Summary: fn.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.Synopsis(pkg.Fset, fn.Decl)}, + Syntax: syntax{Content: pkgsite.Synopsis(fset, fn.Decl)}, + Example: processExamples(fn.Examples, fset), }) } } for _, fn := range docPkg.Funcs { - uid := pkg.PkgPath + "." + fn.Name + uid := docPkg.ImportPath + "." + fn.Name pkgItem.addChild(child(uid)) pkgPage.addItem(&item{ UID: uid, Name: fmt.Sprintf("func %s\n", fn.Name), ID: fn.Name, - Parent: pkg.PkgPath, + Parent: docPkg.ImportPath, Type: "function", Summary: fn.Doc, Langs: onlyGo, - Syntax: syntax{Content: pkgsite.Synopsis(pkg.Fset, fn.Decl)}, + Syntax: syntax{Content: pkgsite.Synopsis(fset, fn.Decl)}, + Example: processExamples(fn.Examples, fset), }) } } @@ -292,3 +325,35 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er } return pages, toc, module, nil } + +// processExamples converts the examples to []example. +// +// Surrounding braces and indentation is removed. +func processExamples(exs []*doc.Example, fset *token.FileSet) []example { + result := []example{} + for _, ex := range exs { + buf := &bytes.Buffer{} + node := &printer.CommentedNode{ + Node: ex.Code, + Comments: ex.Comments, + } + if err := format.Node(buf, fset, node); err != nil { + log.Fatal(err) + } + s := buf.String() + if strings.HasPrefix(s, "{\n") && strings.HasSuffix(s, "\n}") { + lines := strings.Split(s, "\n") + builder := strings.Builder{} + for _, line := range lines[1 : len(lines)-1] { + builder.WriteString(strings.TrimPrefix(line, "\t")) + builder.WriteString("\n") + } + s = builder.String() + } + result = append(result, example{ + Content: s, + Name: ex.Suffix, + }) + } + return result +} diff --git a/internal/godocfx/testdata/golden/index.yml b/internal/godocfx/testdata/golden/index.yml index 4b1200fd534..410f7b5e4d6 100644 --- a/internal/godocfx/testdata/golden/index.yml +++ b/internal/godocfx/testdata/golden/index.yml @@ -242,6 +242,8 @@ items: - go syntax: content: func (a *ACLHandle) Delete(ctx context.Context, entity ACLEntity) (err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// No longer grant access to the bucket to everyone on the Internet.\nif err := client.Bucket(\"my-bucket\").ACL().Delete(ctx, storage.AllUsers); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.ACLHandle.List name: | func (*ACLHandle) List @@ -254,6 +256,8 @@ items: - go syntax: content: func (a *ACLHandle) List(ctx context.Context) (rules []ACLRule, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// List the default object ACLs for my-bucket.\naclRules, err := client.Bucket(\"my-bucket\").DefaultObjectACL().List(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(aclRules)\n" - uid: cloud.google.com/go/storage.ACLHandle.Set name: | func (*ACLHandle) Set @@ -266,6 +270,8 @@ items: - go syntax: content: func (a *ACLHandle) Set(ctx context.Context, entity ACLEntity, role ACLRole) (err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Let any authenticated user read my-bucket/my-object.\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\nif err := obj.ACL().Set(ctx, storage.AllAuthenticatedUsers, storage.RoleReader); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.ACLRole name: ACLRole id: ACLRole @@ -383,6 +389,9 @@ items: - go syntax: content: "type BucketHandle struct {\n\t// contains filtered or unexported fields\n}" + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\nif err == storage.ErrBucketNotExist {\n\tfmt.Println(\"The bucket does not exist\")\n\treturn\n}\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"The bucket exists and has attributes: %#v\\n\", attrs)\n" + name: exists - uid: cloud.google.com/go/storage.BucketHandle.ACL name: | func (*BucketHandle) ACL @@ -411,6 +420,8 @@ items: - go syntax: content: func (b *BucketHandle) AddNotification(ctx context.Context, n *Notification) (ret *Notification, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nn, err := b.AddNotification(ctx, &storage.Notification{\n\tTopicProjectID: \"my-project\",\n\tTopicID: \"my-topic\",\n\tPayloadFormat: storage.JSONPayload,\n})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(n.ID)\n" - uid: cloud.google.com/go/storage.BucketHandle.Attrs name: | func (*BucketHandle) Attrs @@ -423,6 +434,8 @@ items: - go syntax: content: func (b *BucketHandle) Attrs(ctx context.Context) (attrs *BucketAttrs, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(attrs)\n" - uid: cloud.google.com/go/storage.BucketHandle.Create name: | func (*BucketHandle) Create @@ -436,6 +449,8 @@ items: - go syntax: content: func (b *BucketHandle) Create(ctx context.Context, projectID string, attrs *BucketAttrs) (err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nif err := client.Bucket(\"my-bucket\").Create(ctx, \"my-project\", nil); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.DefaultObjectACL name: | func (*BucketHandle) DefaultObjectACL @@ -462,6 +477,8 @@ items: - go syntax: content: func (b *BucketHandle) Delete(ctx context.Context) (err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nif err := client.Bucket(\"my-bucket\").Delete(ctx); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.DeleteNotification name: | func (*BucketHandle) DeleteNotification @@ -474,6 +491,8 @@ items: - go syntax: content: func (b *BucketHandle) DeleteNotification(ctx context.Context, id string) (err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\n// TODO: Obtain notificationID from BucketHandle.AddNotification\n// or BucketHandle.Notifications.\nerr = b.DeleteNotification(ctx, notificationID)\nif err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.IAM name: | func (*BucketHandle) IAM @@ -522,6 +541,8 @@ items: - go syntax: content: func (b *BucketHandle) LockRetentionPolicy(ctx context.Context) error + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nattrs, err := b.Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Note that locking the bucket without first attaching a RetentionPolicy\n// that's at least 1 day is a no-op\nerr = b.If(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).LockRetentionPolicy(ctx)\nif err != nil {\n\t// TODO: handle err\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Notifications name: | func (*BucketHandle) Notifications @@ -535,6 +556,8 @@ items: - go syntax: content: func (b *BucketHandle) Notifications(ctx context.Context) (n map[string]*Notification, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nns, err := b.Notifications(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfor id, n := range ns {\n\tfmt.Printf(\"%s: %+v\\n\", id, n)\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Object name: | func (*BucketHandle) Object @@ -567,6 +590,8 @@ items: - go syntax: content: func (b *BucketHandle) Objects(ctx context.Context, q *Query) *ObjectIterator + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Bucket(\"my-bucket\").Objects(ctx, nil)\n_ = it // TODO: iterate using Next or iterator.Pager.\n" - uid: cloud.google.com/go/storage.BucketHandle.Update name: | func (*BucketHandle) Update @@ -579,6 +604,10 @@ items: - go syntax: content: func (b *BucketHandle) Update(ctx context.Context, uattrs BucketAttrsToUpdate) (attrs *BucketAttrs, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Enable versioning in the bucket, regardless of its previous value.\nattrs, err := client.Bucket(\"my-bucket\").Update(ctx,\n\tstorage.BucketAttrsToUpdate{VersioningEnabled: true})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(attrs)\n" + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nattrs, err := b.Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nvar au storage.BucketAttrsToUpdate\nau.SetLabel(\"lab\", attrs.Labels[\"lab\"]+\"-more\")\nif attrs.Labels[\"delete-me\"] == \"yes\" {\n\tau.DeleteLabel(\"delete-me\")\n}\nattrs, err = b.\n\tIf(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).\n\tUpdate(ctx, au)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(attrs)\n" + name: readModifyWrite - uid: cloud.google.com/go/storage.BucketHandle.UserProject name: | func (*BucketHandle) UserProject @@ -624,6 +653,8 @@ items: - go syntax: content: func (it *BucketIterator) Next() (*BucketAttrs, error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Buckets(ctx, \"my-project\")\nfor {\n\tbucketAttrs, err := it.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(bucketAttrs)\n}\n" - uid: cloud.google.com/go/storage.BucketIterator.PageInfo name: | func (*BucketIterator) PageInfo @@ -718,6 +749,10 @@ items: - go syntax: content: func NewClient(ctx context.Context, opts ...option.ClientOption) (*Client, error) + example: + - content: "ctx := context.Background()\n// Use Google Application Default Credentials to authorize and authenticate the client.\n// More information about Application Default Credentials and how to enable is at\n// https://developers.google.com/identity/protocols/application-default-credentials.\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Use the client.\n\n// Close the client when finished.\nif err := client.Close(); err != nil {\n\t// TODO: handle error.\n}\n" + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx, option.WithoutAuthentication())\nif err != nil {\n\t// TODO: handle error.\n}\n// Use the client.\n\n// Close the client when finished.\nif err := client.Close(); err != nil {\n\t// TODO: handle error.\n}\n" + name: unauthenticated - uid: cloud.google.com/go/storage.Client.Bucket name: | func (*Client) Bucket @@ -753,6 +788,8 @@ items: - go syntax: content: func (c *Client) Buckets(ctx context.Context, projectID string) *BucketIterator + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Buckets(ctx, \"my-bucket\")\n_ = it // TODO: iterate using Next or iterator.Pager.\n" - uid: cloud.google.com/go/storage.Client.Close name: | func (*Client) Close @@ -781,6 +818,8 @@ items: - go syntax: content: func (c *Client) CreateHMACKey(ctx context.Context, projectID, serviceAccountEmail string, ...) (*HMACKey, error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkey, err := client.CreateHMACKey(ctx, \"project-id\", \"service-account-email\")\nif err != nil {\n\t// TODO: handle error.\n}\n_ = hkey // TODO: Use the HMAC Key.\n" - uid: cloud.google.com/go/storage.Client.HMACKeyHandle name: | func (*Client) HMACKeyHandle @@ -811,6 +850,12 @@ items: - go syntax: content: func (c *Client) ListHMACKeys(ctx context.Context, projectID string, opts ...HMACKeyOption) *HMACKeysIterator + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\niter := client.ListHMACKeys(ctx, \"project-id\")\nfor {\n\tkey, err := iter.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = key // TODO: Use the key.\n}\n" + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\niter := client.ListHMACKeys(ctx, \"project-id\", storage.ForHMACKeyServiceAccountEmail(\"service@account.email\"))\nfor {\n\tkey, err := iter.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = key // TODO: Use the key.\n}\n" + name: forServiceAccountEmail + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\niter := client.ListHMACKeys(ctx, \"project-id\", storage.ShowDeletedHMACKeys())\nfor {\n\tkey, err := iter.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = key // TODO: Use the key.\n}\n" + name: showDeletedKeys - uid: cloud.google.com/go/storage.Client.ServiceAccount name: | func (*Client) ServiceAccount @@ -848,6 +893,8 @@ items: - go syntax: content: func (c *Composer) Run(ctx context.Context) (attrs *ObjectAttrs, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nbkt := client.Bucket(\"bucketname\")\nsrc1 := bkt.Object(\"o1\")\nsrc2 := bkt.Object(\"o2\")\ndst := bkt.Object(\"o3\")\n\n// Compose and modify metadata.\nc := dst.ComposerFrom(src1, src2)\nc.ContentType = \"text/plain\"\n\n// Set the expected checksum for the destination object to be validated by\n// the backend (if desired).\nc.CRC32C = 42\nc.SendCRC32C = true\n\nattrs, err := c.Run(ctx)\nif err != nil {\n\t// TODO: Handle error.\n}\nfmt.Println(attrs)\n// Just compose.\nattrs, err = dst.ComposerFrom(src1, src2).Run(ctx)\nif err != nil {\n\t// TODO: Handle error.\n}\nfmt.Println(attrs)\n" - uid: cloud.google.com/go/storage.Conditions name: Conditions id: Conditions @@ -888,6 +935,10 @@ items: - go syntax: content: func (c *Copier) Run(ctx context.Context) (attrs *ObjectAttrs, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nsrc := client.Bucket(\"bucketname\").Object(\"file1\")\ndst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\n// Copy content and modify metadata.\ncopier := dst.CopierFrom(src)\ncopier.ContentType = \"text/plain\"\nattrs, err := copier.Run(ctx)\nif err != nil {\n\t// TODO: Handle error, possibly resuming with copier.RewriteToken.\n}\nfmt.Println(attrs)\n\n// Just copy content.\nattrs, err = dst.CopierFrom(src).Run(ctx)\nif err != nil {\n\t// TODO: Handle error. No way to resume.\n}\nfmt.Println(attrs)\n" + - content: "// Display progress across multiple rewrite RPCs.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nsrc := client.Bucket(\"bucketname\").Object(\"file1\")\ndst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\ncopier := dst.CopierFrom(src)\ncopier.ProgressFunc = func(copiedBytes, totalBytes uint64) {\n\tlog.Printf(\"copy %.1f%% done\", float64(copiedBytes)/float64(totalBytes)*100)\n}\nif _, err := copier.Run(ctx); err != nil {\n\t// TODO: handle error.\n}\n" + name: progress - uid: cloud.google.com/go/storage.HMACKey name: HMACKey id: HMACKey @@ -946,6 +997,8 @@ items: - go syntax: content: func (hkh *HMACKeyHandle) Delete(ctx context.Context, opts ...HMACKeyOption) error + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\n// Make sure that the HMACKey being deleted has a status of inactive.\nif err := hkh.Delete(ctx); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.HMACKeyHandle.Get name: | func (*HMACKeyHandle) Get @@ -964,6 +1017,8 @@ items: - go syntax: content: func (hkh *HMACKeyHandle) Get(ctx context.Context, opts ...HMACKeyOption) (*HMACKey, error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\nhkey, err := hkh.Get(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n_ = hkey // TODO: Use the HMAC Key.\n" - uid: cloud.google.com/go/storage.HMACKeyHandle.Update name: | func (*HMACKeyHandle) Update @@ -978,6 +1033,8 @@ items: - go syntax: content: func (h *HMACKeyHandle) Update(ctx context.Context, au HMACKeyAttrsToUpdate, opts ...HMACKeyOption) (*HMACKey, error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\nukey, err := hkh.Update(ctx, storage.HMACKeyAttrsToUpdate{\n\tState: storage.Inactive,\n})\nif err != nil {\n\t// TODO: handle error.\n}\n_ = ukey // TODO: Use the HMAC Key.\n" - uid: cloud.google.com/go/storage.HMACKeyOption name: HMACKeyOption id: HMACKeyOption @@ -1237,6 +1294,9 @@ items: - go syntax: content: "type ObjectHandle struct {\n\t// contains filtered or unexported fields\n}" + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nattrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\nif err == storage.ErrObjectNotExist {\n\tfmt.Println(\"The object does not exist\")\n\treturn\n}\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"The object exists and has attributes: %#v\\n\", attrs)\n" + name: exists - uid: cloud.google.com/go/storage.ObjectHandle.ACL name: | func (*ObjectHandle) ACL @@ -1264,6 +1324,10 @@ items: - go syntax: content: func (o *ObjectHandle) Attrs(ctx context.Context) (attrs *ObjectAttrs, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(objAttrs)\n" + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n// Read the object.\nobjAttrs1, err := obj.Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Do something else for a while.\ntime.Sleep(5 * time.Minute)\n// Now read the same contents, even if the object has been written since the last read.\nobjAttrs2, err := obj.Generation(objAttrs1.Generation).Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(objAttrs1, objAttrs2)\n" + name: withConditions - uid: cloud.google.com/go/storage.ObjectHandle.BucketName name: | func (*ObjectHandle) BucketName @@ -1311,6 +1375,9 @@ items: - go syntax: content: func (dst *ObjectHandle) CopierFrom(src *ObjectHandle) *Copier + example: + - content: "// To rotate the encryption key on an object, copy it onto itself.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"bucketname\").Object(\"obj\")\n// Assume obj is encrypted with key1, and we want to change to key2.\n_, err = obj.Key(key2).CopierFrom(obj.Key(key1)).Run(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n" + name: rotateEncryptionKeys - uid: cloud.google.com/go/storage.ObjectHandle.Delete name: | func (*ObjectHandle) Delete @@ -1323,6 +1390,8 @@ items: - go syntax: content: func (o *ObjectHandle) Delete(ctx context.Context) error + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// To delete multiple objects in a bucket, list them with an\n// ObjectIterator, then Delete them.\n\n// If you are using this package on the App Engine Flex runtime,\n// you can init a bucket client with your app's default bucket name.\n// See http://godoc.org/google.golang.org/appengine/file#DefaultBucketName.\nbucket := client.Bucket(\"my-bucket\")\nit := bucket.Objects(ctx, nil)\nfor {\n\tobjAttrs, err := it.Next()\n\tif err != nil && err != iterator.Done {\n\t\t// TODO: Handle error.\n\t}\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err := bucket.Object(objAttrs.Name).Delete(ctx); err != nil {\n\t\t// TODO: Handle error.\n\t}\n}\nfmt.Println(\"deleted all object items in the bucket specified.\")\n" - uid: cloud.google.com/go/storage.ObjectHandle.Generation name: | func (*ObjectHandle) Generation @@ -1339,6 +1408,8 @@ items: - go syntax: content: func (o *ObjectHandle) Generation(gen int64) *ObjectHandle + example: + - content: "// Read an object's contents from generation gen, regardless of the\n// current generation of the object.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\nrc, err := obj.Generation(gen).NewReader(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\nif _, err := io.Copy(os.Stdout, rc); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.If name: | func (*ObjectHandle) If @@ -1355,6 +1426,8 @@ items: - go syntax: content: func (o *ObjectHandle) If(conds Conditions) *ObjectHandle + example: + - content: "// Read from an object only if the current generation is gen.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\nrc, err := obj.If(storage.Conditions{GenerationMatch: gen}).NewReader(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nif _, err := io.Copy(os.Stdout, rc); err != nil {\n\t// TODO: handle error.\n}\nif err := rc.Close(); err != nil {\n\tswitch ee := err.(type) {\n\tcase *googleapi.Error:\n\t\tif ee.Code == http.StatusPreconditionFailed {\n\t\t\t// The condition presented in the If failed.\n\t\t\t// TODO: handle error.\n\t\t}\n\n\t\t// TODO: handle other status codes here.\n\n\tdefault:\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.Key name: | func (*ObjectHandle) Key @@ -1371,6 +1444,8 @@ items: - go syntax: content: func (o *ObjectHandle) Key(encryptionKey []byte) *ObjectHandle + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n// Encrypt the object's contents.\nw := obj.Key(secretKey).NewWriter(ctx)\nif _, err := w.Write([]byte(\"top secret\")); err != nil {\n\t// TODO: handle error.\n}\nif err := w.Close(); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.NewRangeReader name: | func (*ObjectHandle) NewRangeReader @@ -1392,6 +1467,12 @@ items: - go syntax: content: func (o *ObjectHandle) NewRangeReader(ctx context.Context, offset, length int64) (r *Reader, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Read only the first 64K.\nrc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, 0, 64*1024)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\n\nslurp, err := ioutil.ReadAll(rc)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"first 64K of file contents:\\n%s\\n\", slurp)\n" + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Read only the last 10 bytes until the end of the file.\nrc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, -10, -1)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\n\nslurp, err := ioutil.ReadAll(rc)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"Last 10 bytes from the end of the file:\\n%s\\n\", slurp)\n" + name: lastNBytes + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Read from the 101st byte until the end of the file.\nrc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, 100, -1)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\n\nslurp, err := ioutil.ReadAll(rc)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"From 101st byte until the end:\\n%s\\n\", slurp)\n" + name: untilEnd - uid: cloud.google.com/go/storage.ObjectHandle.NewReader name: | func (*ObjectHandle) NewReader @@ -1408,6 +1489,8 @@ items: - go syntax: content: func (o *ObjectHandle) NewReader(ctx context.Context) (*Reader, error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nrc, err := client.Bucket(\"my-bucket\").Object(\"my-object\").NewReader(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nslurp, err := ioutil.ReadAll(rc)\nrc.Close()\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"file contents:\", slurp)\n" - uid: cloud.google.com/go/storage.ObjectHandle.NewWriter name: | func (*ObjectHandle) NewWriter @@ -1434,6 +1517,8 @@ items: - go syntax: content: func (o *ObjectHandle) NewWriter(ctx context.Context) *Writer + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n_ = wc // TODO: Use the Writer.\n" - uid: cloud.google.com/go/storage.ObjectHandle.ObjectName name: | func (*ObjectHandle) ObjectName @@ -1472,6 +1557,8 @@ items: - go syntax: content: func (o *ObjectHandle) Update(ctx context.Context, uattrs ObjectAttrsToUpdate) (oa *ObjectAttrs, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Change only the content type of the object.\nobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Update(ctx, storage.ObjectAttrsToUpdate{\n\tContentType: \"text/html\",\n\tContentDisposition: \"\", // delete ContentDisposition\n})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(objAttrs)\n" - uid: cloud.google.com/go/storage.ObjectIterator name: ObjectIterator id: ObjectIterator @@ -1505,6 +1592,8 @@ items: - go syntax: content: func (it *ObjectIterator) Next() (*ObjectAttrs, error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Bucket(\"my-bucket\").Objects(ctx, nil)\nfor {\n\tobjAttrs, err := it.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(objAttrs)\n}\n" - uid: cloud.google.com/go/storage.ObjectIterator.PageInfo name: | func (*ObjectIterator) PageInfo @@ -1554,6 +1643,8 @@ items: - go syntax: content: func GenerateSignedPostPolicyV4(bucket, object string, opts *PostPolicyV4Options) (*PostPolicyV4, error) + example: + - content: "pv4, err := storage.GenerateSignedPostPolicyV4(\"my-bucket\", \"my-object.txt\", &storage.PostPolicyV4Options{\n\tGoogleAccessID: \"my-access-id\",\n\tPrivateKey: []byte(\"my-private-key\"),\n\n\t// The upload expires in 2hours.\n\tExpires: time.Now().Add(2 * time.Hour),\n\n\tFields: &storage.PolicyV4Fields{\n\t\tStatusCodeOnSuccess: 200,\n\t\tRedirectToURLOnSuccess: \"https://example.org/\",\n\t\t// It MUST only be a text file.\n\t\tContentType: \"text/plain\",\n\t},\n\n\t// The conditions that the uploaded file will be expected to conform to.\n\tConditions: []storage.PostPolicyV4Condition{\n\t\t// Make the file a maximum of 10mB.\n\t\tstorage.ConditionContentLengthRange(0, 10<<20),\n\t},\n})\nif err != nil {\n\t// TODO: handle error.\n}\n\n// Now you can upload your file using the generated post policy\n// with a plain HTTP client or even the browser.\nformBuf := new(bytes.Buffer)\nmw := multipart.NewWriter(formBuf)\nfor fieldName, value := range pv4.Fields {\n\tif err := mw.WriteField(fieldName, value); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\nfile := bytes.NewReader(bytes.Repeat([]byte(\"a\"), 100))\n\nmf, err := mw.CreateFormFile(\"file\", \"myfile.txt\")\nif err != nil {\n\t// TODO: handle error.\n}\nif _, err := io.Copy(mf, file); err != nil {\n\t// TODO: handle error.\n}\nif err := mw.Close(); err != nil {\n\t// TODO: handle error.\n}\n\n// Compose the request.\nreq, err := http.NewRequest(\"POST\", pv4.URL, formBuf)\nif err != nil {\n\t// TODO: handle error.\n}\n// Ensure the Content-Type is derived from the multipart writer.\nreq.Header.Set(\"Content-Type\", mw.FormDataContentType())\nres, err := http.DefaultClient.Do(req)\nif err != nil {\n\t// TODO: handle error.\n}\n_ = res\n" - uid: cloud.google.com/go/storage.PostPolicyV4Condition name: PostPolicyV4Condition id: PostPolicyV4Condition @@ -1978,6 +2069,12 @@ items: - go syntax: content: func (w *Writer) Write(p []byte) (n int, err error) + example: + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\nwc.ContentType = \"text/plain\"\nwc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: storage.RoleReader}}\nif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t// TODO: handle error.\n\t// Note that Write may return nil in some error situations,\n\t// so always check the error from Close.\n}\nif err := wc.Close(); err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"updated object:\", wc.Attrs())\n" + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\ndata := []byte(\"verify me\")\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\nwc.CRC32C = crc32.Checksum(data, crc32.MakeTable(crc32.Castagnoli))\nwc.SendCRC32C = true\nif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t// TODO: handle error.\n\t// Note that Write may return nil in some error situations,\n\t// so always check the error from Close.\n}\nif err := wc.Close(); err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"updated object:\", wc.Attrs())\n" + name: checksum + - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\ntctx, cancel := context.WithTimeout(ctx, 30*time.Second)\ndefer cancel() // Cancel when done, whether we time out or not.\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(tctx)\nwc.ContentType = \"text/plain\"\nwc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: storage.RoleReader}}\nif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t// TODO: handle error.\n\t// Note that Write may return nil in some error situations,\n\t// so always check the error from Close.\n}\nif err := wc.Close(); err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"updated object:\", wc.Attrs())\n" + name: timeout - uid: cloud.google.com/go/storage.SignedURL name: | func SignedURL @@ -1993,3 +2090,5 @@ items: - go syntax: content: func SignedURL(bucket, name string, opts *SignedURLOptions) (string, error) + example: + - content: "pkey, err := ioutil.ReadFile(\"my-private-key.pem\")\nif err != nil {\n\t// TODO: handle error.\n}\nurl, err := storage.SignedURL(\"my-bucket\", \"my-object\", &storage.SignedURLOptions{\n\tGoogleAccessID: \"xxx@developer.gserviceaccount.com\",\n\tPrivateKey: pkey,\n\tMethod: \"GET\",\n\tExpires: time.Now().Add(48 * time.Hour),\n})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(url)\n" From 563295135e5785be3b9cf40995b7f8a8401f67b3 Mon Sep 17 00:00:00 2001 From: Tyler Bui-Palsulich Date: Thu, 17 Sep 2020 14:33:02 -0400 Subject: [PATCH 2/3] fix: rename examples field --- internal/godocfx/parse.go | 88 +++++++++++----------- internal/godocfx/testdata/golden/index.yml | 76 +++++++++---------- 2 files changed, 82 insertions(+), 82 deletions(-) diff --git a/internal/godocfx/parse.go b/internal/godocfx/parse.go index 42d69a541d8..40537cdcb0b 100644 --- a/internal/godocfx/parse.go +++ b/internal/godocfx/parse.go @@ -78,7 +78,7 @@ type item struct { Type string `yaml:"type,omitempty"` Langs []string `yaml:"langs,omitempty"` Syntax syntax `yaml:"syntax,omitempty"` - Example []example `yaml:"example,omitempty"` + Examples []example `yaml:"codeexamples,omitempty"` Children []child `yaml:"children,omitempty"` } @@ -174,13 +174,13 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er }) pkgItem := &item{ - UID: docPkg.ImportPath, - Name: docPkg.ImportPath, - ID: docPkg.Name, - Summary: docPkg.Doc, - Langs: onlyGo, - Type: "package", - Example: processExamples(docPkg.Examples, fset), + UID: docPkg.ImportPath, + Name: docPkg.ImportPath, + ID: docPkg.Name, + Summary: docPkg.Doc, + Langs: onlyGo, + Type: "package", + Examples: processExamples(docPkg.Examples, fset), } pkgPage := &page{Items: []*item{pkgItem}} pages[pkgPath] = pkgPage @@ -221,15 +221,15 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er uid := docPkg.ImportPath + "." + t.Name pkgItem.addChild(child(uid)) typeItem := &item{ - UID: uid, - Name: t.Name, - ID: t.Name, - Parent: docPkg.ImportPath, - Type: "type", - Summary: t.Doc, - Langs: onlyGo, - Syntax: syntax{Content: pkgsite.PrintType(fset, t.Decl)}, - Example: processExamples(t.Examples, fset), + UID: uid, + Name: t.Name, + ID: t.Name, + Parent: docPkg.ImportPath, + Type: "type", + Summary: t.Doc, + Langs: onlyGo, + Syntax: syntax{Content: pkgsite.PrintType(fset, t.Decl)}, + Examples: processExamples(t.Examples, fset), } // TODO: items are added as page.Children, rather than // typeItem.Children, as a workaround for the DocFX template. @@ -272,30 +272,30 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er fnUID := uid + "." + fn.Name pkgItem.addChild(child(fnUID)) pkgPage.addItem(&item{ - UID: fnUID, - Name: fmt.Sprintf("func %s\n", fn.Name), - ID: fn.Name, - Parent: uid, - Type: "function", - Summary: fn.Doc, - Langs: onlyGo, - Syntax: syntax{Content: pkgsite.Synopsis(fset, fn.Decl)}, - Example: processExamples(fn.Examples, fset), + UID: fnUID, + Name: fmt.Sprintf("func %s\n", fn.Name), + ID: fn.Name, + Parent: uid, + Type: "function", + Summary: fn.Doc, + Langs: onlyGo, + Syntax: syntax{Content: pkgsite.Synopsis(fset, fn.Decl)}, + Examples: processExamples(fn.Examples, fset), }) } for _, fn := range t.Methods { fnUID := uid + "." + fn.Name pkgItem.addChild(child(fnUID)) pkgPage.addItem(&item{ - UID: fnUID, - Name: fmt.Sprintf("func (%s) %s\n", fn.Recv, fn.Name), - ID: fn.Name, - Parent: uid, - Type: "function", // Note: this is actually a method. - Summary: fn.Doc, - Langs: onlyGo, - Syntax: syntax{Content: pkgsite.Synopsis(fset, fn.Decl)}, - Example: processExamples(fn.Examples, fset), + UID: fnUID, + Name: fmt.Sprintf("func (%s) %s\n", fn.Recv, fn.Name), + ID: fn.Name, + Parent: uid, + Type: "function", // Note: this is actually a method. + Summary: fn.Doc, + Langs: onlyGo, + Syntax: syntax{Content: pkgsite.Synopsis(fset, fn.Decl)}, + Examples: processExamples(fn.Examples, fset), }) } } @@ -303,15 +303,15 @@ func parse(glob string) (map[string]*page, tableOfContents, *packages.Module, er uid := docPkg.ImportPath + "." + fn.Name pkgItem.addChild(child(uid)) pkgPage.addItem(&item{ - UID: uid, - Name: fmt.Sprintf("func %s\n", fn.Name), - ID: fn.Name, - Parent: docPkg.ImportPath, - Type: "function", - Summary: fn.Doc, - Langs: onlyGo, - Syntax: syntax{Content: pkgsite.Synopsis(fset, fn.Decl)}, - Example: processExamples(fn.Examples, fset), + UID: uid, + Name: fmt.Sprintf("func %s\n", fn.Name), + ID: fn.Name, + Parent: docPkg.ImportPath, + Type: "function", + Summary: fn.Doc, + Langs: onlyGo, + Syntax: syntax{Content: pkgsite.Synopsis(fset, fn.Decl)}, + Examples: processExamples(fn.Examples, fset), }) } } diff --git a/internal/godocfx/testdata/golden/index.yml b/internal/godocfx/testdata/golden/index.yml index 410f7b5e4d6..5e630aaa5d3 100644 --- a/internal/godocfx/testdata/golden/index.yml +++ b/internal/godocfx/testdata/golden/index.yml @@ -242,7 +242,7 @@ items: - go syntax: content: func (a *ACLHandle) Delete(ctx context.Context, entity ACLEntity) (err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// No longer grant access to the bucket to everyone on the Internet.\nif err := client.Bucket(\"my-bucket\").ACL().Delete(ctx, storage.AllUsers); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.ACLHandle.List name: | @@ -256,7 +256,7 @@ items: - go syntax: content: func (a *ACLHandle) List(ctx context.Context) (rules []ACLRule, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// List the default object ACLs for my-bucket.\naclRules, err := client.Bucket(\"my-bucket\").DefaultObjectACL().List(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(aclRules)\n" - uid: cloud.google.com/go/storage.ACLHandle.Set name: | @@ -270,7 +270,7 @@ items: - go syntax: content: func (a *ACLHandle) Set(ctx context.Context, entity ACLEntity, role ACLRole) (err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Let any authenticated user read my-bucket/my-object.\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\nif err := obj.ACL().Set(ctx, storage.AllAuthenticatedUsers, storage.RoleReader); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.ACLRole name: ACLRole @@ -389,7 +389,7 @@ items: - go syntax: content: "type BucketHandle struct {\n\t// contains filtered or unexported fields\n}" - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\nif err == storage.ErrBucketNotExist {\n\tfmt.Println(\"The bucket does not exist\")\n\treturn\n}\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"The bucket exists and has attributes: %#v\\n\", attrs)\n" name: exists - uid: cloud.google.com/go/storage.BucketHandle.ACL @@ -420,7 +420,7 @@ items: - go syntax: content: func (b *BucketHandle) AddNotification(ctx context.Context, n *Notification) (ret *Notification, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nn, err := b.AddNotification(ctx, &storage.Notification{\n\tTopicProjectID: \"my-project\",\n\tTopicID: \"my-topic\",\n\tPayloadFormat: storage.JSONPayload,\n})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(n.ID)\n" - uid: cloud.google.com/go/storage.BucketHandle.Attrs name: | @@ -434,7 +434,7 @@ items: - go syntax: content: func (b *BucketHandle) Attrs(ctx context.Context) (attrs *BucketAttrs, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(attrs)\n" - uid: cloud.google.com/go/storage.BucketHandle.Create name: | @@ -449,7 +449,7 @@ items: - go syntax: content: func (b *BucketHandle) Create(ctx context.Context, projectID string, attrs *BucketAttrs) (err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nif err := client.Bucket(\"my-bucket\").Create(ctx, \"my-project\", nil); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.DefaultObjectACL name: | @@ -477,7 +477,7 @@ items: - go syntax: content: func (b *BucketHandle) Delete(ctx context.Context) (err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nif err := client.Bucket(\"my-bucket\").Delete(ctx); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.DeleteNotification name: | @@ -491,7 +491,7 @@ items: - go syntax: content: func (b *BucketHandle) DeleteNotification(ctx context.Context, id string) (err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\n// TODO: Obtain notificationID from BucketHandle.AddNotification\n// or BucketHandle.Notifications.\nerr = b.DeleteNotification(ctx, notificationID)\nif err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.IAM name: | @@ -541,7 +541,7 @@ items: - go syntax: content: func (b *BucketHandle) LockRetentionPolicy(ctx context.Context) error - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nattrs, err := b.Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Note that locking the bucket without first attaching a RetentionPolicy\n// that's at least 1 day is a no-op\nerr = b.If(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).LockRetentionPolicy(ctx)\nif err != nil {\n\t// TODO: handle err\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Notifications name: | @@ -556,7 +556,7 @@ items: - go syntax: content: func (b *BucketHandle) Notifications(ctx context.Context) (n map[string]*Notification, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nns, err := b.Notifications(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfor id, n := range ns {\n\tfmt.Printf(\"%s: %+v\\n\", id, n)\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Object name: | @@ -590,7 +590,7 @@ items: - go syntax: content: func (b *BucketHandle) Objects(ctx context.Context, q *Query) *ObjectIterator - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Bucket(\"my-bucket\").Objects(ctx, nil)\n_ = it // TODO: iterate using Next or iterator.Pager.\n" - uid: cloud.google.com/go/storage.BucketHandle.Update name: | @@ -604,7 +604,7 @@ items: - go syntax: content: func (b *BucketHandle) Update(ctx context.Context, uattrs BucketAttrsToUpdate) (attrs *BucketAttrs, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Enable versioning in the bucket, regardless of its previous value.\nattrs, err := client.Bucket(\"my-bucket\").Update(ctx,\n\tstorage.BucketAttrsToUpdate{VersioningEnabled: true})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(attrs)\n" - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nattrs, err := b.Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nvar au storage.BucketAttrsToUpdate\nau.SetLabel(\"lab\", attrs.Labels[\"lab\"]+\"-more\")\nif attrs.Labels[\"delete-me\"] == \"yes\" {\n\tau.DeleteLabel(\"delete-me\")\n}\nattrs, err = b.\n\tIf(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).\n\tUpdate(ctx, au)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(attrs)\n" name: readModifyWrite @@ -653,7 +653,7 @@ items: - go syntax: content: func (it *BucketIterator) Next() (*BucketAttrs, error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Buckets(ctx, \"my-project\")\nfor {\n\tbucketAttrs, err := it.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(bucketAttrs)\n}\n" - uid: cloud.google.com/go/storage.BucketIterator.PageInfo name: | @@ -749,7 +749,7 @@ items: - go syntax: content: func NewClient(ctx context.Context, opts ...option.ClientOption) (*Client, error) - example: + codeexamples: - content: "ctx := context.Background()\n// Use Google Application Default Credentials to authorize and authenticate the client.\n// More information about Application Default Credentials and how to enable is at\n// https://developers.google.com/identity/protocols/application-default-credentials.\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Use the client.\n\n// Close the client when finished.\nif err := client.Close(); err != nil {\n\t// TODO: handle error.\n}\n" - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx, option.WithoutAuthentication())\nif err != nil {\n\t// TODO: handle error.\n}\n// Use the client.\n\n// Close the client when finished.\nif err := client.Close(); err != nil {\n\t// TODO: handle error.\n}\n" name: unauthenticated @@ -788,7 +788,7 @@ items: - go syntax: content: func (c *Client) Buckets(ctx context.Context, projectID string) *BucketIterator - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Buckets(ctx, \"my-bucket\")\n_ = it // TODO: iterate using Next or iterator.Pager.\n" - uid: cloud.google.com/go/storage.Client.Close name: | @@ -818,7 +818,7 @@ items: - go syntax: content: func (c *Client) CreateHMACKey(ctx context.Context, projectID, serviceAccountEmail string, ...) (*HMACKey, error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkey, err := client.CreateHMACKey(ctx, \"project-id\", \"service-account-email\")\nif err != nil {\n\t// TODO: handle error.\n}\n_ = hkey // TODO: Use the HMAC Key.\n" - uid: cloud.google.com/go/storage.Client.HMACKeyHandle name: | @@ -850,7 +850,7 @@ items: - go syntax: content: func (c *Client) ListHMACKeys(ctx context.Context, projectID string, opts ...HMACKeyOption) *HMACKeysIterator - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\niter := client.ListHMACKeys(ctx, \"project-id\")\nfor {\n\tkey, err := iter.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = key // TODO: Use the key.\n}\n" - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\niter := client.ListHMACKeys(ctx, \"project-id\", storage.ForHMACKeyServiceAccountEmail(\"service@account.email\"))\nfor {\n\tkey, err := iter.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = key // TODO: Use the key.\n}\n" name: forServiceAccountEmail @@ -893,7 +893,7 @@ items: - go syntax: content: func (c *Composer) Run(ctx context.Context) (attrs *ObjectAttrs, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nbkt := client.Bucket(\"bucketname\")\nsrc1 := bkt.Object(\"o1\")\nsrc2 := bkt.Object(\"o2\")\ndst := bkt.Object(\"o3\")\n\n// Compose and modify metadata.\nc := dst.ComposerFrom(src1, src2)\nc.ContentType = \"text/plain\"\n\n// Set the expected checksum for the destination object to be validated by\n// the backend (if desired).\nc.CRC32C = 42\nc.SendCRC32C = true\n\nattrs, err := c.Run(ctx)\nif err != nil {\n\t// TODO: Handle error.\n}\nfmt.Println(attrs)\n// Just compose.\nattrs, err = dst.ComposerFrom(src1, src2).Run(ctx)\nif err != nil {\n\t// TODO: Handle error.\n}\nfmt.Println(attrs)\n" - uid: cloud.google.com/go/storage.Conditions name: Conditions @@ -935,7 +935,7 @@ items: - go syntax: content: func (c *Copier) Run(ctx context.Context) (attrs *ObjectAttrs, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nsrc := client.Bucket(\"bucketname\").Object(\"file1\")\ndst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\n// Copy content and modify metadata.\ncopier := dst.CopierFrom(src)\ncopier.ContentType = \"text/plain\"\nattrs, err := copier.Run(ctx)\nif err != nil {\n\t// TODO: Handle error, possibly resuming with copier.RewriteToken.\n}\nfmt.Println(attrs)\n\n// Just copy content.\nattrs, err = dst.CopierFrom(src).Run(ctx)\nif err != nil {\n\t// TODO: Handle error. No way to resume.\n}\nfmt.Println(attrs)\n" - content: "// Display progress across multiple rewrite RPCs.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nsrc := client.Bucket(\"bucketname\").Object(\"file1\")\ndst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\ncopier := dst.CopierFrom(src)\ncopier.ProgressFunc = func(copiedBytes, totalBytes uint64) {\n\tlog.Printf(\"copy %.1f%% done\", float64(copiedBytes)/float64(totalBytes)*100)\n}\nif _, err := copier.Run(ctx); err != nil {\n\t// TODO: handle error.\n}\n" name: progress @@ -997,7 +997,7 @@ items: - go syntax: content: func (hkh *HMACKeyHandle) Delete(ctx context.Context, opts ...HMACKeyOption) error - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\n// Make sure that the HMACKey being deleted has a status of inactive.\nif err := hkh.Delete(ctx); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.HMACKeyHandle.Get name: | @@ -1017,7 +1017,7 @@ items: - go syntax: content: func (hkh *HMACKeyHandle) Get(ctx context.Context, opts ...HMACKeyOption) (*HMACKey, error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\nhkey, err := hkh.Get(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n_ = hkey // TODO: Use the HMAC Key.\n" - uid: cloud.google.com/go/storage.HMACKeyHandle.Update name: | @@ -1033,7 +1033,7 @@ items: - go syntax: content: func (h *HMACKeyHandle) Update(ctx context.Context, au HMACKeyAttrsToUpdate, opts ...HMACKeyOption) (*HMACKey, error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\nukey, err := hkh.Update(ctx, storage.HMACKeyAttrsToUpdate{\n\tState: storage.Inactive,\n})\nif err != nil {\n\t// TODO: handle error.\n}\n_ = ukey // TODO: Use the HMAC Key.\n" - uid: cloud.google.com/go/storage.HMACKeyOption name: HMACKeyOption @@ -1294,7 +1294,7 @@ items: - go syntax: content: "type ObjectHandle struct {\n\t// contains filtered or unexported fields\n}" - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nattrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\nif err == storage.ErrObjectNotExist {\n\tfmt.Println(\"The object does not exist\")\n\treturn\n}\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"The object exists and has attributes: %#v\\n\", attrs)\n" name: exists - uid: cloud.google.com/go/storage.ObjectHandle.ACL @@ -1324,7 +1324,7 @@ items: - go syntax: content: func (o *ObjectHandle) Attrs(ctx context.Context) (attrs *ObjectAttrs, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(objAttrs)\n" - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n// Read the object.\nobjAttrs1, err := obj.Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Do something else for a while.\ntime.Sleep(5 * time.Minute)\n// Now read the same contents, even if the object has been written since the last read.\nobjAttrs2, err := obj.Generation(objAttrs1.Generation).Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(objAttrs1, objAttrs2)\n" name: withConditions @@ -1375,7 +1375,7 @@ items: - go syntax: content: func (dst *ObjectHandle) CopierFrom(src *ObjectHandle) *Copier - example: + codeexamples: - content: "// To rotate the encryption key on an object, copy it onto itself.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"bucketname\").Object(\"obj\")\n// Assume obj is encrypted with key1, and we want to change to key2.\n_, err = obj.Key(key2).CopierFrom(obj.Key(key1)).Run(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n" name: rotateEncryptionKeys - uid: cloud.google.com/go/storage.ObjectHandle.Delete @@ -1390,7 +1390,7 @@ items: - go syntax: content: func (o *ObjectHandle) Delete(ctx context.Context) error - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// To delete multiple objects in a bucket, list them with an\n// ObjectIterator, then Delete them.\n\n// If you are using this package on the App Engine Flex runtime,\n// you can init a bucket client with your app's default bucket name.\n// See http://godoc.org/google.golang.org/appengine/file#DefaultBucketName.\nbucket := client.Bucket(\"my-bucket\")\nit := bucket.Objects(ctx, nil)\nfor {\n\tobjAttrs, err := it.Next()\n\tif err != nil && err != iterator.Done {\n\t\t// TODO: Handle error.\n\t}\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err := bucket.Object(objAttrs.Name).Delete(ctx); err != nil {\n\t\t// TODO: Handle error.\n\t}\n}\nfmt.Println(\"deleted all object items in the bucket specified.\")\n" - uid: cloud.google.com/go/storage.ObjectHandle.Generation name: | @@ -1408,7 +1408,7 @@ items: - go syntax: content: func (o *ObjectHandle) Generation(gen int64) *ObjectHandle - example: + codeexamples: - content: "// Read an object's contents from generation gen, regardless of the\n// current generation of the object.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\nrc, err := obj.Generation(gen).NewReader(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\nif _, err := io.Copy(os.Stdout, rc); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.If name: | @@ -1426,7 +1426,7 @@ items: - go syntax: content: func (o *ObjectHandle) If(conds Conditions) *ObjectHandle - example: + codeexamples: - content: "// Read from an object only if the current generation is gen.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\nrc, err := obj.If(storage.Conditions{GenerationMatch: gen}).NewReader(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nif _, err := io.Copy(os.Stdout, rc); err != nil {\n\t// TODO: handle error.\n}\nif err := rc.Close(); err != nil {\n\tswitch ee := err.(type) {\n\tcase *googleapi.Error:\n\t\tif ee.Code == http.StatusPreconditionFailed {\n\t\t\t// The condition presented in the If failed.\n\t\t\t// TODO: handle error.\n\t\t}\n\n\t\t// TODO: handle other status codes here.\n\n\tdefault:\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.Key name: | @@ -1444,7 +1444,7 @@ items: - go syntax: content: func (o *ObjectHandle) Key(encryptionKey []byte) *ObjectHandle - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n// Encrypt the object's contents.\nw := obj.Key(secretKey).NewWriter(ctx)\nif _, err := w.Write([]byte(\"top secret\")); err != nil {\n\t// TODO: handle error.\n}\nif err := w.Close(); err != nil {\n\t// TODO: handle error.\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.NewRangeReader name: | @@ -1467,7 +1467,7 @@ items: - go syntax: content: func (o *ObjectHandle) NewRangeReader(ctx context.Context, offset, length int64) (r *Reader, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Read only the first 64K.\nrc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, 0, 64*1024)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\n\nslurp, err := ioutil.ReadAll(rc)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"first 64K of file contents:\\n%s\\n\", slurp)\n" - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Read only the last 10 bytes until the end of the file.\nrc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, -10, -1)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\n\nslurp, err := ioutil.ReadAll(rc)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"Last 10 bytes from the end of the file:\\n%s\\n\", slurp)\n" name: lastNBytes @@ -1489,7 +1489,7 @@ items: - go syntax: content: func (o *ObjectHandle) NewReader(ctx context.Context) (*Reader, error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nrc, err := client.Bucket(\"my-bucket\").Object(\"my-object\").NewReader(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nslurp, err := ioutil.ReadAll(rc)\nrc.Close()\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"file contents:\", slurp)\n" - uid: cloud.google.com/go/storage.ObjectHandle.NewWriter name: | @@ -1517,7 +1517,7 @@ items: - go syntax: content: func (o *ObjectHandle) NewWriter(ctx context.Context) *Writer - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n_ = wc // TODO: Use the Writer.\n" - uid: cloud.google.com/go/storage.ObjectHandle.ObjectName name: | @@ -1557,7 +1557,7 @@ items: - go syntax: content: func (o *ObjectHandle) Update(ctx context.Context, uattrs ObjectAttrsToUpdate) (oa *ObjectAttrs, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Change only the content type of the object.\nobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Update(ctx, storage.ObjectAttrsToUpdate{\n\tContentType: \"text/html\",\n\tContentDisposition: \"\", // delete ContentDisposition\n})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(objAttrs)\n" - uid: cloud.google.com/go/storage.ObjectIterator name: ObjectIterator @@ -1592,7 +1592,7 @@ items: - go syntax: content: func (it *ObjectIterator) Next() (*ObjectAttrs, error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Bucket(\"my-bucket\").Objects(ctx, nil)\nfor {\n\tobjAttrs, err := it.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(objAttrs)\n}\n" - uid: cloud.google.com/go/storage.ObjectIterator.PageInfo name: | @@ -1643,7 +1643,7 @@ items: - go syntax: content: func GenerateSignedPostPolicyV4(bucket, object string, opts *PostPolicyV4Options) (*PostPolicyV4, error) - example: + codeexamples: - content: "pv4, err := storage.GenerateSignedPostPolicyV4(\"my-bucket\", \"my-object.txt\", &storage.PostPolicyV4Options{\n\tGoogleAccessID: \"my-access-id\",\n\tPrivateKey: []byte(\"my-private-key\"),\n\n\t// The upload expires in 2hours.\n\tExpires: time.Now().Add(2 * time.Hour),\n\n\tFields: &storage.PolicyV4Fields{\n\t\tStatusCodeOnSuccess: 200,\n\t\tRedirectToURLOnSuccess: \"https://example.org/\",\n\t\t// It MUST only be a text file.\n\t\tContentType: \"text/plain\",\n\t},\n\n\t// The conditions that the uploaded file will be expected to conform to.\n\tConditions: []storage.PostPolicyV4Condition{\n\t\t// Make the file a maximum of 10mB.\n\t\tstorage.ConditionContentLengthRange(0, 10<<20),\n\t},\n})\nif err != nil {\n\t// TODO: handle error.\n}\n\n// Now you can upload your file using the generated post policy\n// with a plain HTTP client or even the browser.\nformBuf := new(bytes.Buffer)\nmw := multipart.NewWriter(formBuf)\nfor fieldName, value := range pv4.Fields {\n\tif err := mw.WriteField(fieldName, value); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\nfile := bytes.NewReader(bytes.Repeat([]byte(\"a\"), 100))\n\nmf, err := mw.CreateFormFile(\"file\", \"myfile.txt\")\nif err != nil {\n\t// TODO: handle error.\n}\nif _, err := io.Copy(mf, file); err != nil {\n\t// TODO: handle error.\n}\nif err := mw.Close(); err != nil {\n\t// TODO: handle error.\n}\n\n// Compose the request.\nreq, err := http.NewRequest(\"POST\", pv4.URL, formBuf)\nif err != nil {\n\t// TODO: handle error.\n}\n// Ensure the Content-Type is derived from the multipart writer.\nreq.Header.Set(\"Content-Type\", mw.FormDataContentType())\nres, err := http.DefaultClient.Do(req)\nif err != nil {\n\t// TODO: handle error.\n}\n_ = res\n" - uid: cloud.google.com/go/storage.PostPolicyV4Condition name: PostPolicyV4Condition @@ -2069,7 +2069,7 @@ items: - go syntax: content: func (w *Writer) Write(p []byte) (n int, err error) - example: + codeexamples: - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\nwc.ContentType = \"text/plain\"\nwc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: storage.RoleReader}}\nif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t// TODO: handle error.\n\t// Note that Write may return nil in some error situations,\n\t// so always check the error from Close.\n}\nif err := wc.Close(); err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"updated object:\", wc.Attrs())\n" - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\ndata := []byte(\"verify me\")\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\nwc.CRC32C = crc32.Checksum(data, crc32.MakeTable(crc32.Castagnoli))\nwc.SendCRC32C = true\nif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t// TODO: handle error.\n\t// Note that Write may return nil in some error situations,\n\t// so always check the error from Close.\n}\nif err := wc.Close(); err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"updated object:\", wc.Attrs())\n" name: checksum @@ -2090,5 +2090,5 @@ items: - go syntax: content: func SignedURL(bucket, name string, opts *SignedURLOptions) (string, error) - example: + codeexamples: - content: "pkey, err := ioutil.ReadFile(\"my-private-key.pem\")\nif err != nil {\n\t// TODO: handle error.\n}\nurl, err := storage.SignedURL(\"my-bucket\", \"my-object\", &storage.SignedURLOptions{\n\tGoogleAccessID: \"xxx@developer.gserviceaccount.com\",\n\tPrivateKey: pkey,\n\tMethod: \"GET\",\n\tExpires: time.Now().Add(48 * time.Hour),\n})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(url)\n" From 01a5af472fbfe925a28888757f76f22e7ea53075 Mon Sep 17 00:00:00 2001 From: Tyler Bui-Palsulich Date: Thu, 17 Sep 2020 14:44:27 -0400 Subject: [PATCH 3/3] Use executable "Play" examples when available --- internal/godocfx/parse.go | 5 +- internal/godocfx/testdata/golden/index.yml | 96 +++++++++++----------- 2 files changed, 52 insertions(+), 49 deletions(-) diff --git a/internal/godocfx/parse.go b/internal/godocfx/parse.go index 40537cdcb0b..f2448b36e5c 100644 --- a/internal/godocfx/parse.go +++ b/internal/godocfx/parse.go @@ -333,10 +333,13 @@ func processExamples(exs []*doc.Example, fset *token.FileSet) []example { result := []example{} for _, ex := range exs { buf := &bytes.Buffer{} - node := &printer.CommentedNode{ + var node interface{} = &printer.CommentedNode{ Node: ex.Code, Comments: ex.Comments, } + if ex.Play != nil { + node = ex.Play + } if err := format.Node(buf, fset, node); err != nil { log.Fatal(err) } diff --git a/internal/godocfx/testdata/golden/index.yml b/internal/godocfx/testdata/golden/index.yml index 5e630aaa5d3..4990a2d1139 100644 --- a/internal/godocfx/testdata/golden/index.yml +++ b/internal/godocfx/testdata/golden/index.yml @@ -243,7 +243,7 @@ items: syntax: content: func (a *ACLHandle) Delete(ctx context.Context, entity ACLEntity) (err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// No longer grant access to the bucket to everyone on the Internet.\nif err := client.Bucket(\"my-bucket\").ACL().Delete(ctx, storage.AllUsers); err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// No longer grant access to the bucket to everyone on the Internet.\n\tif err := client.Bucket(\"my-bucket\").ACL().Delete(ctx, storage.AllUsers); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.ACLHandle.List name: | func (*ACLHandle) List @@ -257,7 +257,7 @@ items: syntax: content: func (a *ACLHandle) List(ctx context.Context) (rules []ACLRule, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// List the default object ACLs for my-bucket.\naclRules, err := client.Bucket(\"my-bucket\").DefaultObjectACL().List(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(aclRules)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// List the default object ACLs for my-bucket.\n\taclRules, err := client.Bucket(\"my-bucket\").DefaultObjectACL().List(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(aclRules)\n}\n" - uid: cloud.google.com/go/storage.ACLHandle.Set name: | func (*ACLHandle) Set @@ -271,7 +271,7 @@ items: syntax: content: func (a *ACLHandle) Set(ctx context.Context, entity ACLEntity, role ACLRole) (err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Let any authenticated user read my-bucket/my-object.\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\nif err := obj.ACL().Set(ctx, storage.AllAuthenticatedUsers, storage.RoleReader); err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Let any authenticated user read my-bucket/my-object.\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\tif err := obj.ACL().Set(ctx, storage.AllAuthenticatedUsers, storage.RoleReader); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.ACLRole name: ACLRole id: ACLRole @@ -390,7 +390,7 @@ items: syntax: content: "type BucketHandle struct {\n\t// contains filtered or unexported fields\n}" codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\nif err == storage.ErrBucketNotExist {\n\tfmt.Println(\"The bucket does not exist\")\n\treturn\n}\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"The bucket exists and has attributes: %#v\\n\", attrs)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\tattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\n\tif err == storage.ErrBucketNotExist {\n\t\tfmt.Println(\"The bucket does not exist\")\n\t\treturn\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"The bucket exists and has attributes: %#v\\n\", attrs)\n}\n" name: exists - uid: cloud.google.com/go/storage.BucketHandle.ACL name: | @@ -421,7 +421,7 @@ items: syntax: content: func (b *BucketHandle) AddNotification(ctx context.Context, n *Notification) (ret *Notification, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nn, err := b.AddNotification(ctx, &storage.Notification{\n\tTopicProjectID: \"my-project\",\n\tTopicID: \"my-topic\",\n\tPayloadFormat: storage.JSONPayload,\n})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(n.ID)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tn, err := b.AddNotification(ctx, &storage.Notification{\n\t\tTopicProjectID: \"my-project\",\n\t\tTopicID: \"my-topic\",\n\t\tPayloadFormat: storage.JSONPayload,\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(n.ID)\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Attrs name: | func (*BucketHandle) Attrs @@ -435,7 +435,7 @@ items: syntax: content: func (b *BucketHandle) Attrs(ctx context.Context) (attrs *BucketAttrs, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(attrs)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tattrs, err := client.Bucket(\"my-bucket\").Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Create name: | func (*BucketHandle) Create @@ -450,7 +450,7 @@ items: syntax: content: func (b *BucketHandle) Create(ctx context.Context, projectID string, attrs *BucketAttrs) (err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nif err := client.Bucket(\"my-bucket\").Create(ctx, \"my-project\", nil); err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := client.Bucket(\"my-bucket\").Create(ctx, \"my-project\", nil); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.DefaultObjectACL name: | func (*BucketHandle) DefaultObjectACL @@ -478,7 +478,7 @@ items: syntax: content: func (b *BucketHandle) Delete(ctx context.Context) (err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nif err := client.Bucket(\"my-bucket\").Delete(ctx); err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := client.Bucket(\"my-bucket\").Delete(ctx); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.DeleteNotification name: | func (*BucketHandle) DeleteNotification @@ -492,7 +492,7 @@ items: syntax: content: func (b *BucketHandle) DeleteNotification(ctx context.Context, id string) (err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\n// TODO: Obtain notificationID from BucketHandle.AddNotification\n// or BucketHandle.Notifications.\nerr = b.DeleteNotification(ctx, notificationID)\nif err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nvar notificationID string\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\t// TODO: Obtain notificationID from BucketHandle.AddNotification\n\t// or BucketHandle.Notifications.\n\terr = b.DeleteNotification(ctx, notificationID)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.IAM name: | func (*BucketHandle) IAM @@ -542,7 +542,7 @@ items: syntax: content: func (b *BucketHandle) LockRetentionPolicy(ctx context.Context) error codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nattrs, err := b.Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Note that locking the bucket without first attaching a RetentionPolicy\n// that's at least 1 day is a no-op\nerr = b.If(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).LockRetentionPolicy(ctx)\nif err != nil {\n\t// TODO: handle err\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tattrs, err := b.Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Note that locking the bucket without first attaching a RetentionPolicy\n\t// that's at least 1 day is a no-op\n\terr = b.If(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).LockRetentionPolicy(ctx)\n\tif err != nil {\n\t\t// TODO: handle err\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Notifications name: | func (*BucketHandle) Notifications @@ -557,7 +557,7 @@ items: syntax: content: func (b *BucketHandle) Notifications(ctx context.Context) (n map[string]*Notification, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nns, err := b.Notifications(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfor id, n := range ns {\n\tfmt.Printf(\"%s: %+v\\n\", id, n)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tns, err := b.Notifications(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfor id, n := range ns {\n\t\tfmt.Printf(\"%s: %+v\\n\", id, n)\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Object name: | func (*BucketHandle) Object @@ -591,7 +591,7 @@ items: syntax: content: func (b *BucketHandle) Objects(ctx context.Context, q *Query) *ObjectIterator codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Bucket(\"my-bucket\").Objects(ctx, nil)\n_ = it // TODO: iterate using Next or iterator.Pager.\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Bucket(\"my-bucket\").Objects(ctx, nil)\n\t_ = it // TODO: iterate using Next or iterator.Pager.\n}\n" - uid: cloud.google.com/go/storage.BucketHandle.Update name: | func (*BucketHandle) Update @@ -605,8 +605,8 @@ items: syntax: content: func (b *BucketHandle) Update(ctx context.Context, uattrs BucketAttrsToUpdate) (attrs *BucketAttrs, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Enable versioning in the bucket, regardless of its previous value.\nattrs, err := client.Bucket(\"my-bucket\").Update(ctx,\n\tstorage.BucketAttrsToUpdate{VersioningEnabled: true})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(attrs)\n" - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nb := client.Bucket(\"my-bucket\")\nattrs, err := b.Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nvar au storage.BucketAttrsToUpdate\nau.SetLabel(\"lab\", attrs.Labels[\"lab\"]+\"-more\")\nif attrs.Labels[\"delete-me\"] == \"yes\" {\n\tau.DeleteLabel(\"delete-me\")\n}\nattrs, err = b.\n\tIf(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).\n\tUpdate(ctx, au)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(attrs)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Enable versioning in the bucket, regardless of its previous value.\n\tattrs, err := client.Bucket(\"my-bucket\").Update(ctx,\n\t\tstorage.BucketAttrsToUpdate{VersioningEnabled: true})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tb := client.Bucket(\"my-bucket\")\n\tattrs, err := b.Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tvar au storage.BucketAttrsToUpdate\n\tau.SetLabel(\"lab\", attrs.Labels[\"lab\"]+\"-more\")\n\tif attrs.Labels[\"delete-me\"] == \"yes\" {\n\t\tau.DeleteLabel(\"delete-me\")\n\t}\n\tattrs, err = b.\n\t\tIf(storage.BucketConditions{MetagenerationMatch: attrs.MetaGeneration}).\n\t\tUpdate(ctx, au)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" name: readModifyWrite - uid: cloud.google.com/go/storage.BucketHandle.UserProject name: | @@ -654,7 +654,7 @@ items: syntax: content: func (it *BucketIterator) Next() (*BucketAttrs, error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Buckets(ctx, \"my-project\")\nfor {\n\tbucketAttrs, err := it.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(bucketAttrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Buckets(ctx, \"my-project\")\n\tfor {\n\t\tbucketAttrs, err := it.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: Handle error.\n\t\t}\n\t\tfmt.Println(bucketAttrs)\n\t}\n}\n" - uid: cloud.google.com/go/storage.BucketIterator.PageInfo name: | func (*BucketIterator) PageInfo @@ -750,8 +750,8 @@ items: syntax: content: func NewClient(ctx context.Context, opts ...option.ClientOption) (*Client, error) codeexamples: - - content: "ctx := context.Background()\n// Use Google Application Default Credentials to authorize and authenticate the client.\n// More information about Application Default Credentials and how to enable is at\n// https://developers.google.com/identity/protocols/application-default-credentials.\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Use the client.\n\n// Close the client when finished.\nif err := client.Close(); err != nil {\n\t// TODO: handle error.\n}\n" - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx, option.WithoutAuthentication())\nif err != nil {\n\t// TODO: handle error.\n}\n// Use the client.\n\n// Close the client when finished.\nif err := client.Close(); err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\t// Use Google Application Default Credentials to authorize and authenticate the client.\n\t// More information about Application Default Credentials and how to enable is at\n\t// https://developers.google.com/identity/protocols/application-default-credentials.\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Use the client.\n\n\t// Close the client when finished.\n\tif err := client.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/option\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx, option.WithoutAuthentication())\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Use the client.\n\n\t// Close the client when finished.\n\tif err := client.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" name: unauthenticated - uid: cloud.google.com/go/storage.Client.Bucket name: | @@ -789,7 +789,7 @@ items: syntax: content: func (c *Client) Buckets(ctx context.Context, projectID string) *BucketIterator codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Buckets(ctx, \"my-bucket\")\n_ = it // TODO: iterate using Next or iterator.Pager.\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Buckets(ctx, \"my-bucket\")\n\t_ = it // TODO: iterate using Next or iterator.Pager.\n}\n" - uid: cloud.google.com/go/storage.Client.Close name: | func (*Client) Close @@ -819,7 +819,7 @@ items: syntax: content: func (c *Client) CreateHMACKey(ctx context.Context, projectID, serviceAccountEmail string, ...) (*HMACKey, error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkey, err := client.CreateHMACKey(ctx, \"project-id\", \"service-account-email\")\nif err != nil {\n\t// TODO: handle error.\n}\n_ = hkey // TODO: Use the HMAC Key.\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkey, err := client.CreateHMACKey(ctx, \"project-id\", \"service-account-email\")\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = hkey // TODO: Use the HMAC Key.\n}\n" - uid: cloud.google.com/go/storage.Client.HMACKeyHandle name: | func (*Client) HMACKeyHandle @@ -851,10 +851,10 @@ items: syntax: content: func (c *Client) ListHMACKeys(ctx context.Context, projectID string, opts ...HMACKeyOption) *HMACKeysIterator codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\niter := client.ListHMACKeys(ctx, \"project-id\")\nfor {\n\tkey, err := iter.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = key // TODO: Use the key.\n}\n" - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\niter := client.ListHMACKeys(ctx, \"project-id\", storage.ForHMACKeyServiceAccountEmail(\"service@account.email\"))\nfor {\n\tkey, err := iter.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = key // TODO: Use the key.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\titer := client.ListHMACKeys(ctx, \"project-id\")\n\tfor {\n\t\tkey, err := iter.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t\t_ = key // TODO: Use the key.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\titer := client.ListHMACKeys(ctx, \"project-id\", storage.ForHMACKeyServiceAccountEmail(\"service@account.email\"))\n\tfor {\n\t\tkey, err := iter.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t\t_ = key // TODO: Use the key.\n\t}\n}\n" name: forServiceAccountEmail - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\niter := client.ListHMACKeys(ctx, \"project-id\", storage.ShowDeletedHMACKeys())\nfor {\n\tkey, err := iter.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = key // TODO: Use the key.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\titer := client.ListHMACKeys(ctx, \"project-id\", storage.ShowDeletedHMACKeys())\n\tfor {\n\t\tkey, err := iter.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t\t_ = key // TODO: Use the key.\n\t}\n}\n" name: showDeletedKeys - uid: cloud.google.com/go/storage.Client.ServiceAccount name: | @@ -894,7 +894,7 @@ items: syntax: content: func (c *Composer) Run(ctx context.Context) (attrs *ObjectAttrs, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nbkt := client.Bucket(\"bucketname\")\nsrc1 := bkt.Object(\"o1\")\nsrc2 := bkt.Object(\"o2\")\ndst := bkt.Object(\"o3\")\n\n// Compose and modify metadata.\nc := dst.ComposerFrom(src1, src2)\nc.ContentType = \"text/plain\"\n\n// Set the expected checksum for the destination object to be validated by\n// the backend (if desired).\nc.CRC32C = 42\nc.SendCRC32C = true\n\nattrs, err := c.Run(ctx)\nif err != nil {\n\t// TODO: Handle error.\n}\nfmt.Println(attrs)\n// Just compose.\nattrs, err = dst.ComposerFrom(src1, src2).Run(ctx)\nif err != nil {\n\t// TODO: Handle error.\n}\nfmt.Println(attrs)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tbkt := client.Bucket(\"bucketname\")\n\tsrc1 := bkt.Object(\"o1\")\n\tsrc2 := bkt.Object(\"o2\")\n\tdst := bkt.Object(\"o3\")\n\n\t// Compose and modify metadata.\n\tc := dst.ComposerFrom(src1, src2)\n\tc.ContentType = \"text/plain\"\n\n\t// Set the expected checksum for the destination object to be validated by\n\t// the backend (if desired).\n\tc.CRC32C = 42\n\tc.SendCRC32C = true\n\n\tattrs, err := c.Run(ctx)\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(attrs)\n\t// Just compose.\n\tattrs, err = dst.ComposerFrom(src1, src2).Run(ctx)\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(attrs)\n}\n" - uid: cloud.google.com/go/storage.Conditions name: Conditions id: Conditions @@ -936,8 +936,8 @@ items: syntax: content: func (c *Copier) Run(ctx context.Context) (attrs *ObjectAttrs, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nsrc := client.Bucket(\"bucketname\").Object(\"file1\")\ndst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\n// Copy content and modify metadata.\ncopier := dst.CopierFrom(src)\ncopier.ContentType = \"text/plain\"\nattrs, err := copier.Run(ctx)\nif err != nil {\n\t// TODO: Handle error, possibly resuming with copier.RewriteToken.\n}\nfmt.Println(attrs)\n\n// Just copy content.\nattrs, err = dst.CopierFrom(src).Run(ctx)\nif err != nil {\n\t// TODO: Handle error. No way to resume.\n}\nfmt.Println(attrs)\n" - - content: "// Display progress across multiple rewrite RPCs.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nsrc := client.Bucket(\"bucketname\").Object(\"file1\")\ndst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\ncopier := dst.CopierFrom(src)\ncopier.ProgressFunc = func(copiedBytes, totalBytes uint64) {\n\tlog.Printf(\"copy %.1f%% done\", float64(copiedBytes)/float64(totalBytes)*100)\n}\nif _, err := copier.Run(ctx); err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tsrc := client.Bucket(\"bucketname\").Object(\"file1\")\n\tdst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\n\t// Copy content and modify metadata.\n\tcopier := dst.CopierFrom(src)\n\tcopier.ContentType = \"text/plain\"\n\tattrs, err := copier.Run(ctx)\n\tif err != nil {\n\t\t// TODO: Handle error, possibly resuming with copier.RewriteToken.\n\t}\n\tfmt.Println(attrs)\n\n\t// Just copy content.\n\tattrs, err = dst.CopierFrom(src).Run(ctx)\n\tif err != nil {\n\t\t// TODO: Handle error. No way to resume.\n\t}\n\tfmt.Println(attrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"log\"\n)\n\nfunc main() {\n\t// Display progress across multiple rewrite RPCs.\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tsrc := client.Bucket(\"bucketname\").Object(\"file1\")\n\tdst := client.Bucket(\"another-bucketname\").Object(\"file2\")\n\n\tcopier := dst.CopierFrom(src)\n\tcopier.ProgressFunc = func(copiedBytes, totalBytes uint64) {\n\t\tlog.Printf(\"copy %.1f%% done\", float64(copiedBytes)/float64(totalBytes)*100)\n\t}\n\tif _, err := copier.Run(ctx); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" name: progress - uid: cloud.google.com/go/storage.HMACKey name: HMACKey @@ -998,7 +998,7 @@ items: syntax: content: func (hkh *HMACKeyHandle) Delete(ctx context.Context, opts ...HMACKeyOption) error codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\n// Make sure that the HMACKey being deleted has a status of inactive.\nif err := hkh.Delete(ctx); err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\n\t// Make sure that the HMACKey being deleted has a status of inactive.\n\tif err := hkh.Delete(ctx); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.HMACKeyHandle.Get name: | func (*HMACKeyHandle) Get @@ -1018,7 +1018,7 @@ items: syntax: content: func (hkh *HMACKeyHandle) Get(ctx context.Context, opts ...HMACKeyOption) (*HMACKey, error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\nhkey, err := hkh.Get(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n_ = hkey // TODO: Use the HMAC Key.\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\n\thkey, err := hkh.Get(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = hkey // TODO: Use the HMAC Key.\n}\n" - uid: cloud.google.com/go/storage.HMACKeyHandle.Update name: | func (*HMACKeyHandle) Update @@ -1034,7 +1034,7 @@ items: syntax: content: func (h *HMACKeyHandle) Update(ctx context.Context, au HMACKeyAttrsToUpdate, opts ...HMACKeyOption) (*HMACKey, error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nhkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\nukey, err := hkh.Update(ctx, storage.HMACKeyAttrsToUpdate{\n\tState: storage.Inactive,\n})\nif err != nil {\n\t// TODO: handle error.\n}\n_ = ukey // TODO: Use the HMAC Key.\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\thkh := client.HMACKeyHandle(\"project-id\", \"access-key-id\")\n\tukey, err := hkh.Update(ctx, storage.HMACKeyAttrsToUpdate{\n\t\tState: storage.Inactive,\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = ukey // TODO: Use the HMAC Key.\n}\n" - uid: cloud.google.com/go/storage.HMACKeyOption name: HMACKeyOption id: HMACKeyOption @@ -1295,7 +1295,7 @@ items: syntax: content: "type ObjectHandle struct {\n\t// contains filtered or unexported fields\n}" codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nattrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\nif err == storage.ErrObjectNotExist {\n\tfmt.Println(\"The object does not exist\")\n\treturn\n}\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"The object exists and has attributes: %#v\\n\", attrs)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\tattrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\n\tif err == storage.ErrObjectNotExist {\n\t\tfmt.Println(\"The object does not exist\")\n\t\treturn\n\t}\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"The object exists and has attributes: %#v\\n\", attrs)\n}\n" name: exists - uid: cloud.google.com/go/storage.ObjectHandle.ACL name: | @@ -1325,8 +1325,8 @@ items: syntax: content: func (o *ObjectHandle) Attrs(ctx context.Context) (attrs *ObjectAttrs, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(objAttrs)\n" - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n// Read the object.\nobjAttrs1, err := obj.Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Do something else for a while.\ntime.Sleep(5 * time.Minute)\n// Now read the same contents, even if the object has been written since the last read.\nobjAttrs2, err := obj.Generation(objAttrs1.Generation).Attrs(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(objAttrs1, objAttrs2)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(objAttrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\t// Read the object.\n\tobjAttrs1, err := obj.Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Do something else for a while.\n\ttime.Sleep(5 * time.Minute)\n\t// Now read the same contents, even if the object has been written since the last read.\n\tobjAttrs2, err := obj.Generation(objAttrs1.Generation).Attrs(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(objAttrs1, objAttrs2)\n}\n" name: withConditions - uid: cloud.google.com/go/storage.ObjectHandle.BucketName name: | @@ -1376,7 +1376,7 @@ items: syntax: content: func (dst *ObjectHandle) CopierFrom(src *ObjectHandle) *Copier codeexamples: - - content: "// To rotate the encryption key on an object, copy it onto itself.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"bucketname\").Object(\"obj\")\n// Assume obj is encrypted with key1, and we want to change to key2.\n_, err = obj.Key(key2).CopierFrom(obj.Key(key1)).Run(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nvar key1, key2 []byte\n\nfunc main() {\n\t// To rotate the encryption key on an object, copy it onto itself.\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"bucketname\").Object(\"obj\")\n\t// Assume obj is encrypted with key1, and we want to change to key2.\n\t_, err = obj.Key(key2).CopierFrom(obj.Key(key1)).Run(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" name: rotateEncryptionKeys - uid: cloud.google.com/go/storage.ObjectHandle.Delete name: | @@ -1391,7 +1391,7 @@ items: syntax: content: func (o *ObjectHandle) Delete(ctx context.Context) error codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// To delete multiple objects in a bucket, list them with an\n// ObjectIterator, then Delete them.\n\n// If you are using this package on the App Engine Flex runtime,\n// you can init a bucket client with your app's default bucket name.\n// See http://godoc.org/google.golang.org/appengine/file#DefaultBucketName.\nbucket := client.Bucket(\"my-bucket\")\nit := bucket.Objects(ctx, nil)\nfor {\n\tobjAttrs, err := it.Next()\n\tif err != nil && err != iterator.Done {\n\t\t// TODO: Handle error.\n\t}\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err := bucket.Object(objAttrs.Name).Delete(ctx); err != nil {\n\t\t// TODO: Handle error.\n\t}\n}\nfmt.Println(\"deleted all object items in the bucket specified.\")\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// To delete multiple objects in a bucket, list them with an\n\t// ObjectIterator, then Delete them.\n\n\t// If you are using this package on the App Engine Flex runtime,\n\t// you can init a bucket client with your app's default bucket name.\n\t// See http://godoc.org/google.golang.org/appengine/file#DefaultBucketName.\n\tbucket := client.Bucket(\"my-bucket\")\n\tit := bucket.Objects(ctx, nil)\n\tfor {\n\t\tobjAttrs, err := it.Next()\n\t\tif err != nil && err != iterator.Done {\n\t\t\t// TODO: Handle error.\n\t\t}\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err := bucket.Object(objAttrs.Name).Delete(ctx); err != nil {\n\t\t\t// TODO: Handle error.\n\t\t}\n\t}\n\tfmt.Println(\"deleted all object items in the bucket specified.\")\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.Generation name: | func (*ObjectHandle) Generation @@ -1409,7 +1409,7 @@ items: syntax: content: func (o *ObjectHandle) Generation(gen int64) *ObjectHandle codeexamples: - - content: "// Read an object's contents from generation gen, regardless of the\n// current generation of the object.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\nrc, err := obj.Generation(gen).NewReader(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\nif _, err := io.Copy(os.Stdout, rc); err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"io\"\n\t\"os\"\n)\n\nvar gen int64\n\nfunc main() {\n\t// Read an object's contents from generation gen, regardless of the\n\t// current generation of the object.\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\trc, err := obj.Generation(gen).NewReader(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\tif _, err := io.Copy(os.Stdout, rc); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.If name: | func (*ObjectHandle) If @@ -1427,7 +1427,7 @@ items: syntax: content: func (o *ObjectHandle) If(conds Conditions) *ObjectHandle codeexamples: - - content: "// Read from an object only if the current generation is gen.\nctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\nrc, err := obj.If(storage.Conditions{GenerationMatch: gen}).NewReader(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n\nif _, err := io.Copy(os.Stdout, rc); err != nil {\n\t// TODO: handle error.\n}\nif err := rc.Close(); err != nil {\n\tswitch ee := err.(type) {\n\tcase *googleapi.Error:\n\t\tif ee.Code == http.StatusPreconditionFailed {\n\t\t\t// The condition presented in the If failed.\n\t\t\t// TODO: handle error.\n\t\t}\n\n\t\t// TODO: handle other status codes here.\n\n\tdefault:\n\t\t// TODO: handle error.\n\t}\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"google.golang.org/api/googleapi\"\n\t\"io\"\n\t\"net/http\"\n\t\"os\"\n)\n\nvar gen int64\n\nfunc main() {\n\t// Read from an object only if the current generation is gen.\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\trc, err := obj.If(storage.Conditions{GenerationMatch: gen}).NewReader(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\tif _, err := io.Copy(os.Stdout, rc); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := rc.Close(); err != nil {\n\t\tswitch ee := err.(type) {\n\t\tcase *googleapi.Error:\n\t\t\tif ee.Code == http.StatusPreconditionFailed {\n\t\t\t\t// The condition presented in the If failed.\n\t\t\t\t// TODO: handle error.\n\t\t\t}\n\n\t\t\t// TODO: handle other status codes here.\n\n\t\tdefault:\n\t\t\t// TODO: handle error.\n\t\t}\n\t}\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.Key name: | func (*ObjectHandle) Key @@ -1445,7 +1445,7 @@ items: syntax: content: func (o *ObjectHandle) Key(encryptionKey []byte) *ObjectHandle codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n// Encrypt the object's contents.\nw := obj.Key(secretKey).NewWriter(ctx)\nif _, err := w.Write([]byte(\"top secret\")); err != nil {\n\t// TODO: handle error.\n}\nif err := w.Close(); err != nil {\n\t// TODO: handle error.\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nvar secretKey []byte\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tobj := client.Bucket(\"my-bucket\").Object(\"my-object\")\n\t// Encrypt the object's contents.\n\tw := obj.Key(secretKey).NewWriter(ctx)\n\tif _, err := w.Write([]byte(\"top secret\")); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := w.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.NewRangeReader name: | func (*ObjectHandle) NewRangeReader @@ -1468,10 +1468,10 @@ items: syntax: content: func (o *ObjectHandle) NewRangeReader(ctx context.Context, offset, length int64) (r *Reader, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Read only the first 64K.\nrc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, 0, 64*1024)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\n\nslurp, err := ioutil.ReadAll(rc)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"first 64K of file contents:\\n%s\\n\", slurp)\n" - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Read only the last 10 bytes until the end of the file.\nrc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, -10, -1)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\n\nslurp, err := ioutil.ReadAll(rc)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"Last 10 bytes from the end of the file:\\n%s\\n\", slurp)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Read only the first 64K.\n\trc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, 0, 64*1024)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\n\tslurp, err := ioutil.ReadAll(rc)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"first 64K of file contents:\\n%s\\n\", slurp)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Read only the last 10 bytes until the end of the file.\n\trc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, -10, -1)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\n\tslurp, err := ioutil.ReadAll(rc)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"Last 10 bytes from the end of the file:\\n%s\\n\", slurp)\n}\n" name: lastNBytes - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Read from the 101st byte until the end of the file.\nrc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, 100, -1)\nif err != nil {\n\t// TODO: handle error.\n}\ndefer rc.Close()\n\nslurp, err := ioutil.ReadAll(rc)\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Printf(\"From 101st byte until the end:\\n%s\\n\", slurp)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Read from the 101st byte until the end of the file.\n\trc, err := client.Bucket(\"bucketname\").Object(\"filename1\").NewRangeReader(ctx, 100, -1)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdefer rc.Close()\n\n\tslurp, err := ioutil.ReadAll(rc)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Printf(\"From 101st byte until the end:\\n%s\\n\", slurp)\n}\n" name: untilEnd - uid: cloud.google.com/go/storage.ObjectHandle.NewReader name: | @@ -1490,7 +1490,7 @@ items: syntax: content: func (o *ObjectHandle) NewReader(ctx context.Context) (*Reader, error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nrc, err := client.Bucket(\"my-bucket\").Object(\"my-object\").NewReader(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nslurp, err := ioutil.ReadAll(rc)\nrc.Close()\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"file contents:\", slurp)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"io/ioutil\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\trc, err := client.Bucket(\"my-bucket\").Object(\"my-object\").NewReader(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tslurp, err := ioutil.ReadAll(rc)\n\trc.Close()\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"file contents:\", slurp)\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.NewWriter name: | func (*ObjectHandle) NewWriter @@ -1518,7 +1518,7 @@ items: syntax: content: func (o *ObjectHandle) NewWriter(ctx context.Context) *Writer codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n_ = wc // TODO: Use the Writer.\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n\t_ = wc // TODO: Use the Writer.\n}\n" - uid: cloud.google.com/go/storage.ObjectHandle.ObjectName name: | func (*ObjectHandle) ObjectName @@ -1558,7 +1558,7 @@ items: syntax: content: func (o *ObjectHandle) Update(ctx context.Context, uattrs ObjectAttrsToUpdate) (oa *ObjectAttrs, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\n// Change only the content type of the object.\nobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Update(ctx, storage.ObjectAttrsToUpdate{\n\tContentType: \"text/html\",\n\tContentDisposition: \"\", // delete ContentDisposition\n})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(objAttrs)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Change only the content type of the object.\n\tobjAttrs, err := client.Bucket(\"my-bucket\").Object(\"my-object\").Update(ctx, storage.ObjectAttrsToUpdate{\n\t\tContentType: \"text/html\",\n\t\tContentDisposition: \"\", // delete ContentDisposition\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(objAttrs)\n}\n" - uid: cloud.google.com/go/storage.ObjectIterator name: ObjectIterator id: ObjectIterator @@ -1593,7 +1593,7 @@ items: syntax: content: func (it *ObjectIterator) Next() (*ObjectAttrs, error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nit := client.Bucket(\"my-bucket\").Objects(ctx, nil)\nfor {\n\tobjAttrs, err := it.Next()\n\tif err == iterator.Done {\n\t\tbreak\n\t}\n\tif err != nil {\n\t\t// TODO: Handle error.\n\t}\n\tfmt.Println(objAttrs)\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"google.golang.org/api/iterator\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tit := client.Bucket(\"my-bucket\").Objects(ctx, nil)\n\tfor {\n\t\tobjAttrs, err := it.Next()\n\t\tif err == iterator.Done {\n\t\t\tbreak\n\t\t}\n\t\tif err != nil {\n\t\t\t// TODO: Handle error.\n\t\t}\n\t\tfmt.Println(objAttrs)\n\t}\n}\n" - uid: cloud.google.com/go/storage.ObjectIterator.PageInfo name: | func (*ObjectIterator) PageInfo @@ -1644,7 +1644,7 @@ items: syntax: content: func GenerateSignedPostPolicyV4(bucket, object string, opts *PostPolicyV4Options) (*PostPolicyV4, error) codeexamples: - - content: "pv4, err := storage.GenerateSignedPostPolicyV4(\"my-bucket\", \"my-object.txt\", &storage.PostPolicyV4Options{\n\tGoogleAccessID: \"my-access-id\",\n\tPrivateKey: []byte(\"my-private-key\"),\n\n\t// The upload expires in 2hours.\n\tExpires: time.Now().Add(2 * time.Hour),\n\n\tFields: &storage.PolicyV4Fields{\n\t\tStatusCodeOnSuccess: 200,\n\t\tRedirectToURLOnSuccess: \"https://example.org/\",\n\t\t// It MUST only be a text file.\n\t\tContentType: \"text/plain\",\n\t},\n\n\t// The conditions that the uploaded file will be expected to conform to.\n\tConditions: []storage.PostPolicyV4Condition{\n\t\t// Make the file a maximum of 10mB.\n\t\tstorage.ConditionContentLengthRange(0, 10<<20),\n\t},\n})\nif err != nil {\n\t// TODO: handle error.\n}\n\n// Now you can upload your file using the generated post policy\n// with a plain HTTP client or even the browser.\nformBuf := new(bytes.Buffer)\nmw := multipart.NewWriter(formBuf)\nfor fieldName, value := range pv4.Fields {\n\tif err := mw.WriteField(fieldName, value); err != nil {\n\t\t// TODO: handle error.\n\t}\n}\nfile := bytes.NewReader(bytes.Repeat([]byte(\"a\"), 100))\n\nmf, err := mw.CreateFormFile(\"file\", \"myfile.txt\")\nif err != nil {\n\t// TODO: handle error.\n}\nif _, err := io.Copy(mf, file); err != nil {\n\t// TODO: handle error.\n}\nif err := mw.Close(); err != nil {\n\t// TODO: handle error.\n}\n\n// Compose the request.\nreq, err := http.NewRequest(\"POST\", pv4.URL, formBuf)\nif err != nil {\n\t// TODO: handle error.\n}\n// Ensure the Content-Type is derived from the multipart writer.\nreq.Header.Set(\"Content-Type\", mw.FormDataContentType())\nres, err := http.DefaultClient.Do(req)\nif err != nil {\n\t// TODO: handle error.\n}\n_ = res\n" + - content: "package main\n\nimport (\n\t\"bytes\"\n\t\"cloud.google.com/go/storage\"\n\t\"io\"\n\t\"mime/multipart\"\n\t\"net/http\"\n\t\"time\"\n)\n\nfunc main() {\n\tpv4, err := storage.GenerateSignedPostPolicyV4(\"my-bucket\", \"my-object.txt\", &storage.PostPolicyV4Options{\n\t\tGoogleAccessID: \"my-access-id\",\n\t\tPrivateKey: []byte(\"my-private-key\"),\n\n\t\t// The upload expires in 2hours.\n\t\tExpires: time.Now().Add(2 * time.Hour),\n\n\t\tFields: &storage.PolicyV4Fields{\n\t\t\tStatusCodeOnSuccess: 200,\n\t\t\tRedirectToURLOnSuccess: \"https://example.org/\",\n\t\t\t// It MUST only be a text file.\n\t\t\tContentType: \"text/plain\",\n\t\t},\n\n\t\t// The conditions that the uploaded file will be expected to conform to.\n\t\tConditions: []storage.PostPolicyV4Condition{\n\t\t\t// Make the file a maximum of 10mB.\n\t\t\tstorage.ConditionContentLengthRange(0, 10<<20),\n\t\t},\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\t// Now you can upload your file using the generated post policy\n\t// with a plain HTTP client or even the browser.\n\tformBuf := new(bytes.Buffer)\n\tmw := multipart.NewWriter(formBuf)\n\tfor fieldName, value := range pv4.Fields {\n\t\tif err := mw.WriteField(fieldName, value); err != nil {\n\t\t\t// TODO: handle error.\n\t\t}\n\t}\n\tfile := bytes.NewReader(bytes.Repeat([]byte(\"a\"), 100))\n\n\tmf, err := mw.CreateFormFile(\"file\", \"myfile.txt\")\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif _, err := io.Copy(mf, file); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tif err := mw.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n\n\t// Compose the request.\n\treq, err := http.NewRequest(\"POST\", pv4.URL, formBuf)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t// Ensure the Content-Type is derived from the multipart writer.\n\treq.Header.Set(\"Content-Type\", mw.FormDataContentType())\n\tres, err := http.DefaultClient.Do(req)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\t_ = res\n}\n" - uid: cloud.google.com/go/storage.PostPolicyV4Condition name: PostPolicyV4Condition id: PostPolicyV4Condition @@ -2070,10 +2070,10 @@ items: syntax: content: func (w *Writer) Write(p []byte) (n int, err error) codeexamples: - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\nwc.ContentType = \"text/plain\"\nwc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: storage.RoleReader}}\nif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t// TODO: handle error.\n\t// Note that Write may return nil in some error situations,\n\t// so always check the error from Close.\n}\nif err := wc.Close(); err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"updated object:\", wc.Attrs())\n" - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\ndata := []byte(\"verify me\")\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\nwc.CRC32C = crc32.Checksum(data, crc32.MakeTable(crc32.Castagnoli))\nwc.SendCRC32C = true\nif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t// TODO: handle error.\n\t// Note that Write may return nil in some error situations,\n\t// so always check the error from Close.\n}\nif err := wc.Close(); err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"updated object:\", wc.Attrs())\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n\twc.ContentType = \"text/plain\"\n\twc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: storage.RoleReader}}\n\tif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t\t// TODO: handle error.\n\t\t// Note that Write may return nil in some error situations,\n\t\t// so always check the error from Close.\n\t}\n\tif err := wc.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"updated object:\", wc.Attrs())\n}\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"hash/crc32\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tdata := []byte(\"verify me\")\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(ctx)\n\twc.CRC32C = crc32.Checksum(data, crc32.MakeTable(crc32.Castagnoli))\n\twc.SendCRC32C = true\n\tif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t\t// TODO: handle error.\n\t\t// Note that Write may return nil in some error situations,\n\t\t// so always check the error from Close.\n\t}\n\tif err := wc.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"updated object:\", wc.Attrs())\n}\n" name: checksum - - content: "ctx := context.Background()\nclient, err := storage.NewClient(ctx)\nif err != nil {\n\t// TODO: handle error.\n}\ntctx, cancel := context.WithTimeout(ctx, 30*time.Second)\ndefer cancel() // Cancel when done, whether we time out or not.\nwc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(tctx)\nwc.ContentType = \"text/plain\"\nwc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: storage.RoleReader}}\nif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t// TODO: handle error.\n\t// Note that Write may return nil in some error situations,\n\t// so always check the error from Close.\n}\nif err := wc.Close(); err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(\"updated object:\", wc.Attrs())\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"context\"\n\t\"fmt\"\n\t\"time\"\n)\n\nfunc main() {\n\tctx := context.Background()\n\tclient, err := storage.NewClient(ctx)\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\ttctx, cancel := context.WithTimeout(ctx, 30*time.Second)\n\tdefer cancel() // Cancel when done, whether we time out or not.\n\twc := client.Bucket(\"bucketname\").Object(\"filename1\").NewWriter(tctx)\n\twc.ContentType = \"text/plain\"\n\twc.ACL = []storage.ACLRule{{Entity: storage.AllUsers, Role: storage.RoleReader}}\n\tif _, err := wc.Write([]byte(\"hello world\")); err != nil {\n\t\t// TODO: handle error.\n\t\t// Note that Write may return nil in some error situations,\n\t\t// so always check the error from Close.\n\t}\n\tif err := wc.Close(); err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(\"updated object:\", wc.Attrs())\n}\n" name: timeout - uid: cloud.google.com/go/storage.SignedURL name: | @@ -2091,4 +2091,4 @@ items: syntax: content: func SignedURL(bucket, name string, opts *SignedURLOptions) (string, error) codeexamples: - - content: "pkey, err := ioutil.ReadFile(\"my-private-key.pem\")\nif err != nil {\n\t// TODO: handle error.\n}\nurl, err := storage.SignedURL(\"my-bucket\", \"my-object\", &storage.SignedURLOptions{\n\tGoogleAccessID: \"xxx@developer.gserviceaccount.com\",\n\tPrivateKey: pkey,\n\tMethod: \"GET\",\n\tExpires: time.Now().Add(48 * time.Hour),\n})\nif err != nil {\n\t// TODO: handle error.\n}\nfmt.Println(url)\n" + - content: "package main\n\nimport (\n\t\"cloud.google.com/go/storage\"\n\t\"fmt\"\n\t\"io/ioutil\"\n\t\"time\"\n)\n\nfunc main() {\n\tpkey, err := ioutil.ReadFile(\"my-private-key.pem\")\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\turl, err := storage.SignedURL(\"my-bucket\", \"my-object\", &storage.SignedURLOptions{\n\t\tGoogleAccessID: \"xxx@developer.gserviceaccount.com\",\n\t\tPrivateKey: pkey,\n\t\tMethod: \"GET\",\n\t\tExpires: time.Now().Add(48 * time.Hour),\n\t})\n\tif err != nil {\n\t\t// TODO: handle error.\n\t}\n\tfmt.Println(url)\n}\n"