docs(appmesh): clarifying the difference between constructor and method to create a resource

packages/@aws-cdk/aws-appmesh/README.md

@@ -72,24 +72,29 @@ const router = mesh.addVirtualRouter('router', {
 });
 ```
 
-The router can also be created using the constructor and passing in the mesh instead of calling the `addVirtualRouter()` method for the mesh.
-The same pattern applies to all constructs within the appmesh library, for any mesh.addXZY method, a new constuctor can also be used.
-This is particularly useful for cross stack resources are required.
-Where creating the `mesh` as part of an infrastructure stack and creating the `resources` such as `nodes` is more useful to keep in the application stack.
+Note that creating the router using the `addVirtualRouter()` method places it in the same Stack that the mesh belongs to
+(which might be different from the current Stack).
+The router can also be created using the constructor of `VirtualRouter` and passing in the mesh instead of calling the `addVirtualRouter()` method.
+This is particularly useful when splitting your resources between many Stacks,
+like creating the `mesh` as part of an infrastructure stack,
+but the other resources, such as routers, in the application stack:
 
 ```ts
-const mesh = new Mesh(stack, 'AppMesh', {
+const mesh = new Mesh(infraStack, 'AppMesh', {
  meshName: 'myAwsmMesh',
- egressFilter: MeshFilterType.Allow_All,
+ egressFilter: MeshFilterType.ALLOW_ALL,
 });
 
-const router = new VirtualRouter(stack, 'router', {
- mesh, // notice that mesh is a required property when creating a router with a new statement
- listeners: [ appmesh.VirtualRouterListener.http(8081) ]
- }
+// the VirtualRouter will belong to 'appStack',
+// even though the Mesh belongs to 'infraStack'
+const router = new VirtualRouter(appStack, 'router', {
+ mesh: mesh, // notice that mesh is a required property when creating a router with the 'new' statement
+ listeners: [appmesh.VirtualRouterListener.http(8081)],
 });
 ```
 
+The same is true for other `add*()` methods in the AppMesh library.
+
 The _VirtualRouterListener_ class provides an easy interface for defining new protocol specific listeners.
 The `http()`, `http2()`, `grpc()` and `tcp()` methods are available for use.
 They accept a single port parameter, that is used to define what port to match requests on.

packages/@aws-cdk/aws-appmesh/lib/mesh.ts

@@ -23,7 +23,7 @@ export enum MeshFilterType {
 }
 
 /**
- * Interface wich all Mesh based classes MUST implement
+ * Interface which all Mesh based classes MUST implement
  */
 export interface IMesh extends cdk.IResource {
  /**
@@ -41,17 +41,23 @@ export interface IMesh extends cdk.IResource {
  readonly meshArn: string;
 
  /**
- * Adds a VirtualRouter to the Mesh with the given id and props
+ * Creates a new VirtualRouter in this Mesh.
+ * Note that the Router is created in the same Stack that this Mesh belongs to,
+ * which might be different than the current stack.
  */
  addVirtualRouter(id: string, props?: VirtualRouterBaseProps): VirtualRouter;
 
  /**
- * Adds a VirtualNode to the Mesh
+ * Creates a new VirtualNode in this Mesh.
+ * Note that the Node is created in the same Stack that this Mesh belongs to,
+ * which might be different than the current stack.
  */
  addVirtualNode(id: string, props?: VirtualNodeBaseProps): VirtualNode;
 
  /**
- * Adds a VirtualGateway to the Mesh
+ * Creates a new VirtualGateway in this Mesh.
+ * Note that the Gateway is created in the same Stack that this Mesh belongs to,
+ * which might be different than the current stack.
  */
  addVirtualGateway(id: string, props?: VirtualGatewayBaseProps): VirtualGateway;
 }
@@ -108,7 +114,7 @@ export interface MeshProps {
  /**
  * The name of the Mesh being defined
  *
- * @default - A name is autmoatically generated
+ * @default - A name is automatically generated
  */
  readonly meshName?: string;