resource/aws_ram_resource_share_accepter: Minor adjustments and documentation enhancements for initial release

Reference: #8259

Output from acceptance testing:

```
--- PASS: TestAccAwsRamResourceShareAccepter_basic (31.57s)
```

Author: bflad

aws/resource_aws_ram_resource_share_accepter.go

@@ -82,15 +82,17 @@ func resourceAwsRamResourceShareAccepterCreate(d *schema.ResourceData, meta inte
 
 	shareARN := d.Get("share_arn").(string)
 
-	// need invitation arn
 	invitation, err := resourceAwsRamResourceShareGetInvitation(conn, shareARN, ram.ResourceShareInvitationStatusPending)
 
 	if err != nil {
 		return err
 	}
 
 	if invitation == nil || aws.StringValue(invitation.ResourceShareInvitationArn) == "" {
-		return fmt.Errorf("No RAM resource share invitation by ARN (%s) found", shareARN)
+		return fmt.Errorf(
+			"No RAM Resource Share (%s) invitation found\n\n" +
+			"NOTE: If both AWS accounts are in the same AWS Organization and RAM Sharing with AWS Organizations is enabled, this resource is not necessary",
+			shareARN)
 	}
 
 	input := &ram.AcceptResourceShareInvitationInput{
@@ -225,7 +227,7 @@ func resourceAwsRamResourceShareGetInvitation(conn *ram.RAM, resourceShareARN, s
 		for _, rsi := range page.ResourceShareInvitations {
 			if aws.StringValue(rsi.Status) == status {
 				invitation = rsi
-				break
+				return false
 			}
 		}
 

aws/resource_aws_ram_resource_share_accepter_test.go

@@ -72,11 +72,12 @@ func testAccCheckAwsRamResourceShareAccepterDestroy(s *terraform.State) error {
 			return fmt.Errorf("Error deleting RAM resource share: %s", err)
 		}
 
-		if len(output.ResourceShares) == 0 {
-			return nil
+		if len(output.ResourceShares) > 0 && aws.StringValue(output.ResourceShares[0].Status) != ram.ResourceShareStatusDeleted {
+			return fmt.Errorf("RAM resource share invitation found, should be destroyed")
 		}
 	}
-	return fmt.Errorf("RAM resource share invitation found, should be destroyed")
+
+	return nil
 }
 
 func testAccCheckAwsRamResourceShareAccepterExists(name string) resource.TestCheckFunc {

website/aws.erb

@@ -324,9 +324,6 @@
                                 </li>
                             </ul>
                         </li>
-                        <li>
-                        <a href="/docs/providers/aws/r/ram_resource_share_accepter.html">aws_ram_resource_share_accepter</a>
-                        </li>
                     </ul>
                 </li>
                 <li>
@@ -2280,6 +2277,9 @@
                                 <li>
                                     <a href="/docs/providers/aws/r/ram_resource_share.html">aws_ram_resource_share</a>
                                 </li>
+                                <li>
+                                    <a href="/docs/providers/aws/r/ram_resource_share_accepter.html">aws_ram_resource_share_accepter</a>
+                                </li>
                             </ul>
                         </li>
                     </ul>

website/docs/r/ram_principal_association.markdown

@@ -8,9 +8,17 @@ description: |-
 
 # Resource: aws_ram_principal_association
 
-Provides a Resource Access Manager (RAM) principal association.
+Provides a Resource Access Manager (RAM) principal association. Depending if [RAM Sharing with AWS Organizations is enabled](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-orgs), the RAM behavior with different principal types changes.
 
-~> *NOTE:* For an AWS Account ID principal, the target account must accept the RAM association invitation after resource creation.
+When RAM Sharing with AWS Organizations is enabled:
+
+- For AWS Account ID, Organization, and Organizational Unit principals within the same AWS Organization, no resource share invitation is sent and resources become available automatically after creating the association.
+- For AWS Account ID principals outside the AWS Organization, a resource share invitation is sent and must be accepted before resources become available. See the [`aws_ram_resource_share_accepter` resource](/docs/providers/aws/r/ram_resource_share_accepter.html) to accept these invitations.
+
+When RAM Sharing with AWS Organizations is not enabled:
+
+- Organization and Organizational Unit principals cannot be used.
+- For AWS Account ID principals, a resource share invitation is sent and must be accepted before resources become available. See the [`aws_ram_resource_share_accepter` resource](/docs/providers/aws/r/ram_resource_share_accepter.html) to accept these invitations.
 
 ## Example Usage
 

website/docs/r/ram_resource_share_accepter.markdown

@@ -10,7 +10,7 @@ description: |-
 
 Manage accepting a Resource Access Manager (RAM) Resource Share invitation. From a _receiver_ AWS account, accept an invitation to share resources that were shared by a _sender_ AWS account. To create a resource share in the _sender_, see the [`aws_ram_resource_share` resource](/docs/providers/aws/r/ram_resource_share.html).
 
-~> **Note:** You can [`share resources`](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html) with Organizations, Organizational Units (OUs), AWS accounts, and accounts from outside of your Organization.
+~> **Note:** If both AWS accounts are in the same Organization and [RAM Sharing with AWS Organizations is enabled](https://docs.aws.amazon.com/ram/latest/userguide/getting-started-sharing.html#getting-started-sharing-orgs), this resource is not necessary as RAM Resource Share invitations are not used.
 
 ## Example Usage