Merge pull request #439 from ekristen/docs-contributing-dev

docs: updating contributing resources/dev docs

docs/documentation.md

@@ -31,9 +31,21 @@ The underlying library that drives the bulk of this tool is [libnuke](https://gi
 has tooling to help generate documentation for a resource. Primary the library focuses on inspecting the resource struct
 and generating documentation based on the fields of the struct for properties.
 
-There's an additional sub command called `generate-resource-docs` that is hidden from standard usage. This command is
-used to generate documentation for a resource and write it to disk. This command leverages the struct inspection to get
-details about the properties and intertwine them with the markdown template to generate the documentation.
+There's an additional tool called `generate-docs`. This command is used to generate documentation for a resource and
+write it to disk. This command leverages the struct inspection to get details about the properties and intertwine them
+with the markdown template to generate the documentation.
 
 However, for this to work the resource needs to be updated to export all it's fields. This is done by capitalizing the
 first letter of the field name. The field name should match what the existing property name is if it is defined.
+
+#### Generating Documentation for All Resources
+
+```console
+go run tools/generate-docs/main.go --write
+```
+
+#### Generating Documentation for a Single Resource
+
+```console
+go run tools/generate-docs/main.go --resource EC2Instance --write
+```

docs/resources.md

@@ -27,35 +27,40 @@ It can optionally have the following methods defined:
 package resources
 
 import (
-    "context"
-    
-    "github.com/ekristen/libnuke/pkg/resource"
-    "github.com/ekristen/libnuke/pkg/types"
+	"context"
+
+	"github.com/ekristen/libnuke/pkg/resource"
+	"github.com/ekristen/libnuke/pkg/types"
 
-    "github.com/ekristen/aws-nuke/v3/pkg/nuke"
+	"github.com/ekristen/aws-nuke/v3/pkg/nuke"
 )
 
 type ExampleResource struct {
-    ID *string
+	ID *string `description:"The ID of the resource"`
 }
 
 func (r *ExampleResource) Remove(_ context.Context) error {
-    // remove the resource, an error will put the resource in failed state
-    // resources in failed state are retried a number of times
-    return nil
+	// remove the resource, an error will put the resource in failed state
+	// resources in failed state are retried a number of times
+	return nil
 }
 
 func (r *ExampleResource) Filter() error {
-    // filter the resource, this is useful for built-in resources that cannot
-    // be removed, like an AWS managed resource, return an error here to filter
-    // it before it even gets to the user supplied filters.
-    return nil
+	// filter the resource, this is useful for built-in resources that cannot
+	// be removed, like an AWS managed resource, return an error here to filter
+	// it before it even gets to the user supplied filters.
+	return nil
 }
 
 func (r *ExampleResource) String() string {
-    // return a string representation of the resource, this is legacy, but still
-    // used for a number of reasons.
-    return *r.ID
+	// return a string representation of the resource, this is legacy, but still
+	// used for a number of reasons.
+	return *r.ID
+}
+
+func (r *ExampleResource) Properties() types.Properties {
+    // return a properties representation of the resource via struct inspection
+	return types.NewPropertiesFromStruct(r)
 }
 ```
 
@@ -116,7 +121,7 @@ func (l *ExampleResourceLister) List(_ context.Context, o interface{}) ([]resour
 // -----------------------------------------------------------------------------
 
 type ExampleResource struct {
-	ID *string
+	ID *string `description:"The unique ID of the resource"`
 }
 
 func (r *ExampleResource) Remove(_ context.Context) error {
@@ -139,10 +144,8 @@ func (r *ExampleResource) String() string {
 }
 
 func (r *ExampleResource) Properties() types.Properties {
-	// return a properties representation of the resource
-	props := types.NewProperties()
-	props.Set("ID", r.ID)
-	return props
+	// return a properties representation of the resource from struct inspection
+	return types.NewPropertiesFromStruct(r)
 }
 ```
 
@@ -279,7 +282,7 @@ func init() {
 
 type SNSTopic struct {
 	svc      *sns.SNS
-	TopicARN *string
+	TopicARN *string `description:"The ARN of the SNS Topic"`
 	Tags     []*sns.Tag
 }