Another pass at adding field level documentation for #78 (#161)

internal/provider/data_source_epcc_catalog.go

@@ -12,8 +12,9 @@ func dataSourceEpccCatalog() *schema.Resource {
 		ReadContext: addDiagToContext(dataSourceEpccCatalogRead),
 		Schema: map[string]*schema.Schema{
 			"id": {
-				Type:     schema.TypeString,
-				Required: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				Description: "The id of the catalog.",
 			},
 			"name": {
 				Type:        schema.TypeString,

internal/provider/data_source_epcc_catalog_rules.go

@@ -12,8 +12,9 @@ func dataSourceEpccCatalogRule() *schema.Resource {
 		ReadContext: addDiagToContext(dataSourceEpccCatalogRuleRead),
 		Schema: map[string]*schema.Schema{
 			"id": {
-				Type:     schema.TypeString,
-				Required: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				Description: "The unique identifier of the catalog rule.",
 			},
 			"name": {
 				Type:        schema.TypeString,

internal/provider/data_source_epcc_file.go

@@ -11,30 +11,36 @@ func dataSourceEpccFile() *schema.Resource {
 		ReadContext: addDiagToContext(dataSourceEpccFileRead),
 		Schema: map[string]*schema.Schema{
 			"id": {
-				Type:     schema.TypeString,
-				Required: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				Description: "The unique identifier for the file.",
 			},
 			"file_name": {
-				Type:     schema.TypeString,
-				Optional: true,
-				ForceNew: true,
+				Type:        schema.TypeString,
+				Optional:    true,
+				ForceNew:    true,
+				Description: "The name of the file",
 			},
 			"file_link": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "A link to the file",
 			},
 			"mime_type": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The MIME type of the file",
 			},
 			"file_size": {
-				Type:     schema.TypeInt,
-				Computed: true,
+				Type:        schema.TypeInt,
+				Computed:    true,
+				Description: "The size of the file",
 			},
 			"public": {
-				Type:     schema.TypeBool,
-				Optional: true,
-				ForceNew: true,
+				Type:        schema.TypeBool,
+				Optional:    true,
+				ForceNew:    true,
+				Description: "Whether the file is public.",
 			},
 		},
 	}

internal/provider/data_source_epcc_hierarchy.go

@@ -11,20 +11,24 @@ func dataSourceEpccHierarchy() *schema.Resource {
 		ReadContext: addDiagToContext(dataSourceEpccHierarchyRead),
 		Schema: map[string]*schema.Schema{
 			"id": {
-				Type:     schema.TypeString,
-				Required: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				Description: "The unique identifier of the hierarchy.",
 			},
 			"name": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The name of the hierarchy. The maximum length is 1000 characters.",
 			},
 			"description": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "A description of the hierarchy.",
 			},
 			"slug": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "A unique slug for the hierarchy.",
 			},
 		},
 	}

internal/provider/data_source_epcc_node.go

@@ -12,28 +12,34 @@ func dataSourceEpccNode() *schema.Resource {
 		ReadContext: addDiagToContext(dataSourceEpccNodeRead),
 		Schema: map[string]*schema.Schema{
 			"id": {
-				Type:     schema.TypeString,
-				Required: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				Description: "The unique identifier of the node.",
 			},
 			"hierarchy_id": {
-				Type:     schema.TypeString,
-				Required: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				Description: "The unique identifier of the hierarchy.",
 			},
 			"name": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "A name for the node. Names must be unique among sibling nodes in the hierarchy, but otherwise a name can be non-unique. Cannot be null.",
 			},
 			"description": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "A description of the node.",
 			},
 			"slug": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "A slug for the node. Slugs must be unique among sibling nodes in the hierarchy, but otherwise a slug can be non-unique.",
 			},
 			"parent_id": {
-				Type:     schema.TypeString,
-				Optional: true,
+				Type:        schema.TypeString,
+				Optional:    true,
+				Description: "The node ID for the parent node. The new node is created as a child of this parent node.",
 			},
 		},
 	}

internal/provider/data_source_epcc_node_product.go

@@ -17,19 +17,22 @@ func dataSourceEpccNodeProduct() *schema.Resource {
 				Required: true,
 			},
 			"hierarchy_id": {
-				Type:     schema.TypeString,
-				Required: true,
-				ForceNew: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				ForceNew:    true,
+				Description: "The unique identifier of the hierarchy.",
 			},
 			"node_id": {
-				Type:     schema.TypeString,
-				Required: true,
-				ForceNew: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				ForceNew:    true,
+				Description: "The unique identifier of the node in the hierarchy.",
 			},
 			"product_id": {
-				Type:     schema.TypeString,
-				Required: true,
-				ForceNew: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				ForceNew:    true,
+				Description: "The unique identifier of the product.",
 			},
 		},
 	}

internal/provider/data_source_epcc_pricebook.go

@@ -12,16 +12,19 @@ func dataSourceEpccPricebook() *schema.Resource {
 		ReadContext: addDiagToContext(dataSourceEpccPricebookRead),
 		Schema: map[string]*schema.Schema{
 			"id": {
-				Type:     schema.TypeString,
-				Required: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				Description: "The unique identifier of the price book.",
 			},
 			"name": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "A unique name for the price book.",
 			},
 			"description": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The purpose for the price book, such as flash sale pricing or preferred customer pricing.",
 			},
 		},
 	}

internal/provider/data_source_epcc_promotion.go

@@ -11,12 +11,11 @@ func dataSourceEpccPromotion() *schema.Resource {
 		ReadContext: addDiagToContext(dataSourceEpccPromotionRead),
 		Schema: map[string]*schema.Schema{
 			"id":             {Type: schema.TypeString, Required: true},
-			"type":           {Type: schema.TypeString, Computed: true},
-			"name":           {Type: schema.TypeString, Computed: true},
-			"description":    {Type: schema.TypeString, Computed: true},
-			"enabled":        {Type: schema.TypeBool, Computed: true},
-			"automatic":      {Type: schema.TypeBool, Optional: true},
-			"promotion_type": {Type: schema.TypeString, Computed: true},
+			"name":           {Type: schema.TypeString, Computed: true, Description: "Specifies a name for the promotion."},
+			"description":    {Type: schema.TypeString, Computed: true, Description: "Specifies a description for the promotion."},
+			"enabled":        {Type: schema.TypeBool, Computed: true, Description: "Specifies whether the promotion is enabled. The options are `true` or `false`, and the default setting is `false`."},
+			"automatic":      {Type: schema.TypeBool, Optional: true, Description: "Specifies whether the promotion is applied automatically to the cart or a code is required to apply the promotion. The default setting is `false`. When this value is set `true`, a code is autogenerated. If this value is set `false`, you must create the code manually"},
+			"promotion_type": {Type: schema.TypeString, Computed: true, Description: "Specifies the type of the promotion."},
 			"schema": {Type: schema.TypeList, Required: true,
 				Elem: &schema.Resource{Schema: map[string]*schema.Schema{
 					"currencies": {Type: schema.TypeList, Optional: true,
@@ -25,14 +24,14 @@ func dataSourceEpccPromotion() *schema.Resource {
 							"amount":   {Type: schema.TypeInt, Optional: true},
 						}}},
 				}}},
-			"start": {Type: schema.TypeString, Computed: true},
-			"end":   {Type: schema.TypeString, Computed: true},
-			"min_cart_value": {Type: schema.TypeList, Optional: true,
+			"start": {Type: schema.TypeString, Computed: true, Description: "Specifies the start date and time of the promotion or the start date of the promotion. You can provide a specific time in the HH:MM format. For example, `\"start\": \"2000-01-01 12:00\"`."},
+			"end":   {Type: schema.TypeString, Computed: true, Description: "Specifies the end date and time of the promotion or the end date of the promotion."},
+			"min_cart_value": {Type: schema.TypeList, Optional: true, Description: "Provide the minimum cart value required for the promotion to apply.",
 				Elem: &schema.Resource{Schema: map[string]*schema.Schema{
 					"promotion": {Type: schema.TypeString, Optional: true},
 					"amount":    {Type: schema.TypeInt, Optional: true},
 				}}},
-			"max_discount_value": {Type: schema.TypeList, Optional: true,
+			"max_discount_value": {Type: schema.TypeList, Optional: true, Description: "Provides the maximum possible discount for the cart",
 				Elem: &schema.Resource{Schema: map[string]*schema.Schema{
 					"promotion": {Type: schema.TypeString, Optional: true},
 					"amount":    {Type: schema.TypeInt, Optional: true},

internal/provider/data_source_epcc_settings.go

@@ -10,10 +10,10 @@ func dataSourceEpccSettings() *schema.Resource {
 	return &schema.Resource{
 		ReadContext: addDiagToContext(dataSourceEpccSettingsRead),
 		Schema: map[string]*schema.Schema{
-			"page_length":          {Type: schema.TypeInt, Computed: true},
-			"list_child_products":  {Type: schema.TypeBool, Computed: true},
-			"additional_languages": {Type: schema.TypeList, Computed: true, Elem: &schema.Schema{Type: schema.TypeString}},
-			"calculation_method":   {Type: schema.TypeString, Computed: true},
+			"page_length":          {Type: schema.TypeInt, Computed: true, Description: "The number of results per page when paginating results"},
+			"list_child_products":  {Type: schema.TypeBool, Computed: true, Description: "Whether to display child products in product listings."},
+			"additional_languages": {Type: schema.TypeList, Computed: true, Elem: &schema.Schema{Type: schema.TypeString}, Description: "You can define additional language codes that are enabled for a project, this applies only to the legacy catalog and does not apply to PCM products, hierarchies, and catalogs."},
+			"calculation_method":   {Type: schema.TypeString, Computed: true, Description: "This option defines the method used to calculate cart and order totals."},
 		},
 	}
 }

internal/provider/provider_test.go

@@ -36,18 +36,26 @@ func TestProvider(t *testing.T) {
 
 	resourceAttributesWithNoDescription := make([]string, 0)
 
+	totalBadCount := 0
 	for key, resource := range provider.ResourcesMap {
 
 		if resource.Description == "" {
 			resourcesWithNoDescription = append(resourcesWithNoDescription, key)
 		}
 
-		for attributeName, schema := range resource.Schema {
+		count := 0
+		for _, schema := range resource.Schema {
+
 			if schema.Description == "" {
-				resourceAttributesWithNoDescription = append(resourceAttributesWithNoDescription, fmt.Sprintf("Resource %s attribute %s", key, attributeName))
+				count++
+				totalBadCount++
 			}
 		}
 
+		if count > 0 {
+			resourceAttributesWithNoDescription = append(resourceAttributesWithNoDescription, fmt.Sprintf("%s => %d", key, count))
+		}
+
 	}
 
 	dataSourcesWithNoDescription := make([]string, 0)
@@ -57,11 +65,16 @@ func TestProvider(t *testing.T) {
 			dataSourcesWithNoDescription = append(dataSourcesWithNoDescription, key)
 		}
 
-		for attributeName, schema := range dataSource.Schema {
+		count := 0
+		for _, schema := range dataSource.Schema {
 			if schema.Description == "" {
-				dataSourceAttributesWithNoDescription = append(dataSourceAttributesWithNoDescription, fmt.Sprintf("Resource %s attribute %s", key, attributeName))
+				count++
+				totalBadCount++
 			}
 		}
+		if count > 0 {
+			dataSourceAttributesWithNoDescription = append(dataSourceAttributesWithNoDescription, fmt.Sprintf("%s => %d", key, count))
+		}
 	}
 
 	dataSourceAndResourcesMissingDescriptions := len(resourcesWithNoDescription) + len(dataSourcesWithNoDescription)
@@ -70,12 +83,11 @@ func TestProvider(t *testing.T) {
 		t.Fatalf("%d object's don't have descriptions:\n\tResources:%s\nData Sources:%s\n", dataSourceAndResourcesMissingDescriptions, resourcesWithNoDescription, dataSourcesWithNoDescription)
 	}
 
-	dataSourceAndResourceAttributesMissingDescription := len(resourceAttributesWithNoDescription) + len(dataSourceAttributesWithNoDescription)
 	currentDay := int(time.Now().Unix() / 86400)
 	currentTarget := max(19110-currentDay, 0)
 
-	if dataSourceAndResourceAttributesMissingDescription > currentTarget {
-		t.Fatalf("%d object's don't have descriptions\n\tWe have a lot of technical debt so this tests permits a non zero value but over time decreases the number of descriptions needed by 1 per day, so just go and get below this number: %d\n\tResources:%s\nData Sources:%s\n", dataSourceAndResourceAttributesMissingDescription, currentTarget, resourceAttributesWithNoDescription, dataSourceAttributesWithNoDescription)
+	if totalBadCount+10 > currentTarget {
+		t.Fatalf("%d object's don't have descriptions\n\tWe have a lot of technical debt so this tests permits a non zero value but over time decreases the number of descriptions needed by 1 per day, so just go and get below this number: %d\n\tResources:%s\nData Sources:%s\n", totalBadCount, currentTarget, resourceAttributesWithNoDescription, dataSourceAttributesWithNoDescription)
 	}
 
 }

internal/provider/resource_epcc_catalog.go

@@ -19,27 +19,32 @@ func resourceEpccCatalog() *schema.Resource {
 		},
 		Schema: map[string]*schema.Schema{
 			"id": {
-				Type:     schema.TypeString,
-				Computed: true,
+				Type:        schema.TypeString,
+				Computed:    true,
+				Description: "The id of the catalog.",
 			},
 			"name": {
-				Type:     schema.TypeString,
-				Required: true,
+				Type:        schema.TypeString,
+				Required:    true,
+				Description: "The name of the catalog.",
 			},
 			"description": {
-				Type:     schema.TypeString,
-				Optional: true,
+				Type:        schema.TypeString,
+				Optional:    true,
+				Description: " A description of the catalog, such as the purpose for the catalog.",
 			},
 			"hierarchies": {
 				Type:     schema.TypeSet,
 				Optional: true,
 				Elem: &schema.Schema{
 					Type: schema.TypeString,
 				},
+				Description: "The unique identifiers of the hierarchies to associate with this catalog.",
 			},
 			"pricebook": {
-				Type:     schema.TypeString,
-				Optional: true,
+				Type:        schema.TypeString,
+				Optional:    true,
+				Description: "The unique identifier of the price book to associate with this catalog.",
 			},
 		},
 	}