Repo sync for protected CLA branch

docs/atl/reference/ccomdynamicunkarray-class.md

@@ -35,7 +35,7 @@ class CComDynamicUnkArray
 |[CComDynamicUnkArray::end](#end)|Returns a pointer to one past the last `IUnknown` pointer in the collection.|
 |[CComDynamicUnkArray::GetAt](#getat)|Retrieves the element at the specified index.|
 |[CComDynamicUnkArray::GetCookie](#getcookie)|Call this method to get the cookie associated with a given `IUnknown` pointer.|
-|[CComDynamicUnkArray::GetSize](#getsize)|Returns the length of an array.|
+|[CComDynamicUnkArray::GetSize](#getsize)|Returns the number of elements the array can store.|
 |[CComDynamicUnkArray::GetUnknown](#getunknown)|Call this method to get the `IUnknown` pointer associated with a given cookie.|
 |[CComDynamicUnkArray::Remove](#remove)|Call this method to remove an `IUnknown` pointer from the array.|
 
@@ -69,7 +69,12 @@ The `IUnknown` pointer to add to the array.
 
 ### Return Value
 
-Returns the cookie associated with the newly added pointer.
+Returns the cookie associated with the newly added pointer. Use this cookie to retrieve the pointer from the array with [CComDynamicUnkArray::GetAt](#getat).
+
+### Remarks
+
+The position where this item is inserted won't necessarily be directly after the last-inserted item if `Remove()` was previously called on this array. Use the returned cookie to reliably access the inserted pointer.
+The array's size might be increased to accommodate more items. Use `GetSize()` to get the new size.
 
 ## <a name="begin"></a> CComDynamicUnkArray::begin
 
@@ -92,7 +97,7 @@ Before using the `IUnknown` interface, you should check that it is not NULL.
 
 ## <a name="clear"></a> CComDynamicUnkArray::clear
 
-Empties the array.
+Empties the array. Resets the size to 0.
 
 ```cpp
 void clear();
@@ -124,7 +129,9 @@ Frees resources allocated by the class constructor.
 
 ## <a name="end"></a> CComDynamicUnkArray::end
 
-Returns a pointer to one past the last `IUnknown` pointer in the collection.
+Returns a pointer to one-past the last element in the array's allocated buffer.
+
+Note: this means that the last-inserted pointer is not guaranteed to be at `end()-1` because the array may not be filled to capacity.
 
 ```
 IUnknown**
@@ -150,7 +157,7 @@ The index of the element to retrieve.
 
 ### Return Value
 
-A pointer to an [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) interface.
+A pointer to an [IUnknown](/windows/win32/api/unknwn/nn-unknwn-iunknown) interface if an element was previously added and exists at this index; otherwise `NULL`.
 
 ## <a name="getcookie"></a> CComDynamicUnkArray::GetCookie
 
@@ -175,17 +182,19 @@ If there is more than one instance of the same `IUnknown` pointer, this function
 
 ## <a name="getsize"></a> CComDynamicUnkArray::GetSize
 
-Returns the length of an array.
+Returns the allocated capacity of the array.
+
+Note: this is not the same as the number of non-NULL elements currently in the array.
 
 ```
 int GetSize() const;
 ```
 
 ### Return Value
 
-The length of the array.
+The number of elements the array can store. `GetSize() == end() - begin()`.
 
-## <a name="getunknown"></a> CComDynamicUnkArray::GetUnknown
+##  <a name="getunknown"></a> CComDynamicUnkArray::GetUnknown
 
 Call this method to get the `IUnknown` pointer associated with a given cookie.
 
@@ -206,6 +215,8 @@ Returns the `IUnknown` pointer, or NULL if no matching cookie is found.
 
 Call this method to remove an `IUnknown` pointer from the array.
 
+All other elements are unchanged and retain their index and cookie.
+
 ```
 BOOL Remove(DWORD dwCookie);
 ```