Add custom documentation generation logic

.gitignore

@@ -1,2 +1,4 @@
 vendor
 doc
+.yardoc
+Gemfile.lock

.yardopts

@@ -0,0 +1,5 @@
+--plugin go
+-m markdown
+-o doc/api
+aws/**/*.go
+service/**/*.go

Gemfile

@@ -0,0 +1,6 @@
+source 'https://rubygems.org'
+
+gem 'yard', git: 'git://github.com/lsegal/yard'
+gem 'yard-go', git: 'git://github.com/lsegal/yard-go'
+gem 'rdiscount'
+

Makefile

@@ -6,6 +6,7 @@ help:
 	@echo "  api_info                to print a list of services and versions"
 	@echo "  build                   to go build the SDK"
 	@echo "  deps                    to go get the SDK dependencies"
+	@echo "  docs                    to build SDK documentation"
 	@echo "  generate                to go generate and make services"
 	@echo "  generate-protocol-test  to generate protocol tests"
 	@echo "  integration             to run integration tests"
@@ -44,6 +45,9 @@ unit: deps build lint
 build:
 	go build ./...
 
+docs:
+	bundle install && bundle exec yard
+
 deps:
 	@go get ./...
 	@go get github.com/lsegal/gucumber/cmd/gucumber

aws/awserr/error.go

@@ -10,23 +10,23 @@ package awserr
 //
 // Example:
 //
-//    output, err := s3manage.Upload(svc, input, opts)
-//    if err != nil {
-//        if awsErr, ok := err.(awserr.Error); ok {
-//            // Get error details
-//            log.Println("Error:", err.Code(), err.Message())
+//     output, err := s3manage.Upload(svc, input, opts)
+//     if err != nil {
+//         if awsErr, ok := err.(awserr.Error); ok {
+//             // Get error details
+//             log.Println("Error:", err.Code(), err.Message())
 //
-//            Prints out full error message, including original error if there was one.
-//            log.Println("Error:", err.Error())
+//             // Prints out full error message, including original error if there was one.
+//             log.Println("Error:", err.Error())
 //
-//            // Get original error
-//            if origErr := err.Err(); origErr != nil {
-//                // operate on original error.
-//            }
-//        } else {
-//            fmt.Println(err.Error())
-//        }
-//    }
+//             // Get original error
+//             if origErr := err.Err(); origErr != nil {
+//                 // operate on original error.
+//             }
+//         } else {
+//             fmt.Println(err.Error())
+//         }
+//     }
 //
 type Error interface {
 	// Satisfy the generic error interface.

aws/credentials/chain_provider.go

@@ -7,6 +7,8 @@ import (
 var (
 	// ErrNoValidProvidersFoundInChain Is returned when there are no valid
 	// providers in the ChainProvider.
+	//
+	// @readonly
 	ErrNoValidProvidersFoundInChain = awserr.New("NoCredentialProviders", "no valid providers in chain", nil)
 )
 

aws/credentials/credentials.go

@@ -63,6 +63,7 @@ import (
 //     svc := s3.New(&aws.Config{Credentials: AnonymousCredentials})
 //     // Access public S3 buckets.
 //
+// @readonly
 var AnonymousCredentials = NewStaticCredentials("", "", "")
 
 // A Value is the AWS credentials value for individual credential fields.

aws/credentials/ec2_role_provider.go

@@ -31,7 +31,6 @@ const metadataCredentialsEndpoint = "http://169.254.169.254/latest/meta-data/iam
 //         // specified the credentials will be expired early
 //         ExpiryWindow: 0,
 //     }
-//
 type EC2RoleProvider struct {
 	Expiry
 

aws/credentials/env_provider.go

@@ -9,18 +9,24 @@ import (
 var (
 	// ErrAccessKeyIDNotFound is returned when the AWS Access Key ID can't be
 	// found in the process's environment.
+	//
+	// @readonly
 	ErrAccessKeyIDNotFound = awserr.New("EnvAccessKeyNotFound", "AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY not found in environment", nil)
+
 	// ErrSecretAccessKeyNotFound is returned when the AWS Secret Access Key
 	// can't be found in the process's environment.
+	//
+	// @readonly
 	ErrSecretAccessKeyNotFound = awserr.New("EnvSecretNotFound", "AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY not found in environment", nil)
 )
 
 // A EnvProvider retrieves credentials from the environment variables of the
 // running process. Environment credentials never expire.
 //
 // Environment variables used:
-// - Access Key ID:     AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY
-// - Secret Access Key: AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY
+//
+// * Access Key ID:     AWS_ACCESS_KEY_ID or AWS_ACCESS_KEY
+// * Secret Access Key: AWS_SECRET_ACCESS_KEY or AWS_SECRET_KEY
 type EnvProvider struct {
 	retrieved bool
 }

aws/credentials/shared_credentials_provider.go

@@ -12,6 +12,8 @@ import (
 
 var (
 	// ErrSharedCredentialsHomeNotFound is emitted when the user directory cannot be found.
+	//
+	// @readonly
 	ErrSharedCredentialsHomeNotFound = awserr.New("UserHomeNotFound", "user home directory not found.", nil)
 )
 

aws/credentials/static_provider.go

@@ -6,6 +6,8 @@ import (
 
 var (
 	// ErrStaticCredentialsEmpty is emitted when static credentials are empty.
+	//
+	// @readonly
 	ErrStaticCredentialsEmpty = awserr.New("EmptyStaticCreds", "static credentials are empty", nil)
 )
 

aws/handler_functions.go

@@ -134,10 +134,14 @@ func AfterRetryHandler(r *Request) {
 var (
 	// ErrMissingRegion is an error that is returned if region configuration is
 	// not found.
+	//
+	// @readonly
 	ErrMissingRegion error = awserr.New("MissingRegion", "could not find region configuration", nil)
 
 	// ErrMissingEndpoint is an error that is returned if an endpoint cannot be
 	// resolved for a service.
+	//
+	// @readonly
 	ErrMissingEndpoint error = awserr.New("MissingEndpoint", "'Endpoint' configuration is required for this service", nil)
 )