documentation rework (#608)

Author: bmoffatt

README.md

@@ -1,18 +1,9 @@
 # AWS Lambda for Go 
 
-[![tests][1]][2]
-[![Go Reference][5]][6]
-[![GoCard][7]][8]
-[![codecov][9]][10]
-
-[1]: https://github.com/aws/aws-lambda-go/workflows/tests/badge.svg
-[2]: https://github.com/aws/aws-lambda-go/actions?query=workflow%3Atests
-[5]: https://pkg.go.dev/badge/github.com/aws/aws-lambda-go.svg
-[6]: https://pkg.go.dev/github.com/aws/aws-lambda-go
-[7]: https://goreportcard.com/badge/github.com/aws/aws-lambda-go
-[8]: https://goreportcard.com/report/github.com/aws/aws-lambda-go
-[9]: https://codecov.io/gh/aws/aws-lambda-go/branch/master/graph/badge.svg
-[10]: https://codecov.io/gh/aws/aws-lambda-go
+[![tests](https://github.com/aws/aws-lambda-go/workflows/tests/badge.svg)](https://github.com/aws/aws-lambda-go/actions?query=workflow%3Atests)
+[![Go Reference](https://pkg.go.dev/badge/github.com/aws/aws-lambda-go.svg)](https://pkg.go.dev/github.com/aws/aws-lambda-go)
+[![GoCard](https://goreportcard.com/badge/github.com/aws/aws-lambda-go)](https://goreportcard.com/report/github.com/aws/aws-lambda-go)
+[![codecov](https://codecov.io/gh/aws/aws-lambda-go/branch/master/graph/badge.svg)](https://codecov.io/gh/aws/aws-lambda-go)
 
 Libraries, samples, and tools to help Go developers develop AWS Lambda functions.
 
@@ -108,5 +99,7 @@ To deploy your function, refer to the official documentation for [deploying usin
 
 # Event Integrations
 
-The [event models](https://github.com/aws/aws-lambda-go/tree/master/events) can be used to model AWS event sources. The official documentation has [detailed walkthroughs](https://docs.aws.amazon.com/lambda/latest/dg/use-cases.html).
+[![events package](https://pkg.go.dev/badge/github.com/aws/aws-lambda-go/events.svg)](https://pkg.go.dev/github.com/aws/aws-lambda-go/events)
+
+The events package provides type definitions for common AWS event sources. The official documentation has [detailed walkthroughs](https://docs.aws.amazon.com/lambda/latest/dg/use-cases.html).
 

cfn/README.md

@@ -0,0 +1,11 @@
+// Package cfn provides helpers for implementing AWS CloudFormation custom resources.
+//
+// CloudFormation custom resources allow you to write custom provisioning logic that CloudFormation
+// runs when you create, update, or delete stacks. This package handles the response protocol,
+// making it easier to implement custom resource handlers.
+//
+// The LambdaWrap helper catches errors and ensures proper responses are sent to CloudFormation's
+// pre-signed URL, preventing stack operations from hanging.
+//
+// See https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html
+package cfn

cfn/doc.go

@@ -0,0 +1,25 @@
+package cfn_test
+
+import (
+	"context"
+
+	"github.com/aws/aws-lambda-go/cfn"
+	"github.com/aws/aws-lambda-go/lambda"
+)
+
+// CloudFormation custom resources require a different response handling due to the way stacks execute.
+// The cfn.LambdaWrap helper catches all errors and ensures the correct response is sent to the
+// pre-signed URL that comes with the event.
+//
+// This example safely 'Echo' back anything given into the Echo parameter within the Custom Resource call.
+func Example() {
+	lambda.Start(cfn.LambdaWrap(func(ctx context.Context, event cfn.Event) (physicalResourceID string, data map[string]interface{}, err error) {
+		v, _ := event.ResourceProperties["Echo"].(string)
+
+		data = map[string]interface{}{
+			"Echo": v,
+		}
+
+		return
+	}))
+}