Merged PR 21152: Adding missing descriptions, and improving others

Adding missing descriptions, and improving others

Author: Steven White

windows.devices.enumeration.pnp/pnpobjecttype.md

@@ -16,7 +16,7 @@ public enum Windows.Devices.Enumeration.Pnp.PnpObjectType : int
 >
 > The alternative to **PnpObjectType** is the [Windows.Devices.Enumeration.DeviceInformationKind](/uwp/api/windows.devices.enumeration.deviceinformationkind) enum, which you can pass as a parameter to **Windows.Devices.Enumeration** APIs. For example, instead of using **PnpObjectType** when you create a **PnpObjectWatcher**, use **DeviceInformationKind** when you create a [DeviceWatcher](/uwp/api/windows.devices.enumeration.devicewatcher).
 
-Indicates the type of device represented by the [PnpObject](pnpobject.md).
+Defines constants that specify the type of device represented by the [PnpObject](pnpobject.md).
 
 ## -enum-fields
 
@@ -58,7 +58,7 @@ The [PnpObject](pnpobject.md) represents a device input panel.
 
 ### -field AssociationEndpointProtocol: 9
 
-TBD
+Specifies that the [PnpObject](pnpobject.md) represents an association endpoint protocol.
 
 ## -remarks
 

windows.devices.enumeration/deviceinformation_createfromidasync_1003420271.md

@@ -30,7 +30,9 @@ The type of [DeviceInformation](deviceinformation.md) object that you want to cr
 
 ### -param settings
 
-Enumeration settings come from a device API's **GetDeviceEnumerationSettings** method, and contain opaque data. An object implementing this must also implement the **IDeviceEnumerationSettings** interface.
+The argument passed in *settings* is an object that implements **IDeviceEnumerationSettings**; but otherwise, the object is of an opaque marker class (that is, it has no public properties or methods). The purpose of *settings* is to retrieve extended parameters from a device-specific API for device-specific scenarios that aren't possible in the standard WDE API. You can think of the parameters like extra knobs that the API surface doesn't allow.
+
+The *settings* object would come from a device API's **GetDeviceEnumerationSettings** method, and would contain opaque data. But currently there are no APIs that produce the object.
 
 ## -returns
 

windows.devices.enumeration/deviceinformation_createfromidasync_728202765.md

@@ -25,7 +25,6 @@ An object for starting and managing the asynchronous creation of the [DeviceInfo
 The savedId variable in this example is a [DeviceInformation](deviceinformation.md) ID previously saved by the application, obtained from the [id](deviceinformation_id.md) property of the last-used [DeviceInformation](deviceinformation.md) object.
 
 ```javascript
-
     // Create a DeviceInformation object from a saved ID
     var Enum = Windows.Devices.Enumeration;
     var DevInf = Enum.DeviceInformation;
@@ -40,7 +39,5 @@ The savedId variable in this example is a [DeviceInformation](deviceinformation.
 
 ```
 
-
-
 ## -see-also
-[CreateFromIdAsync(String, IIterable_1)](deviceinformation_createfromidasync_907774063.md)
+[CreateFromIdAsync(String, IIterable_1)](deviceinformation_createfromidasync_907774063.md)

windows.devices.enumeration/deviceinformation_createfromidasync_907774063.md

@@ -28,7 +28,6 @@ An object for starting and managing the asynchronous creation of the [DeviceInfo
 The following example builds a list of properties to include in the [DeviceInformation](deviceinformation.md) object to create from a [DeviceInformation](deviceinformation.md) ID.The savedId variable in this example is a [DeviceInformation](deviceinformation.md) ID previously saved by the application, obtained from the [id](deviceinformation_id.md) property of the last-used [DeviceInformation](deviceinformation.md) object.
 
 ```javascript
-
     // Create a set of two additional properties
     var propertiesToRetrieve = new Array();
     propertiesToRetrieve.push("System.InterfaceClassGuid");
@@ -45,12 +44,7 @@ The following example builds a list of properties to include in the [DeviceInfor
         function (e) {
             displayError("Failed to create DeviceInformation: " + e.message);
         });
-
-
-
 ```
 
-
-
 ## -see-also
-[CreateFromIdAsync(String)](deviceinformation_createfromidasync_728202765.md)
+[CreateFromIdAsync(String)](deviceinformation_createfromidasync_728202765.md)

windows.devices.enumeration/deviceinformationcustompairing_pairingsetmembersrequested.md

@@ -12,7 +12,7 @@ public event Windows.Foundation.TypedEventHandler<Windows.Devices.Enumeration.De
 
 ## -description
 
-TBD. For more info, and code examples, see [Pairing a set with the DeviceInformationPairing.Custom property](/windows/uwp/devices-sensors/pairing-a-set).
+Raised when the member(s) of a pairing set have been requested. For more info, and code examples, see [Pairing a set with the DeviceInformationPairing.Custom property](/windows/uwp/devices-sensors/pairing-a-set).
 
 ## -remarks
 

windows.devices.enumeration/deviceinformationkind.md

@@ -11,7 +11,7 @@ public enum Windows.Devices.Enumeration.DeviceInformationKind : int
 
 ## -description
 
-Represents the kind of [DeviceInformation](deviceinformation.md) object.
+Defines constants that specify a kind of [DeviceInformation](deviceinformation.md) object.
 
 ## -enum-fields
 
@@ -73,7 +73,37 @@ The [Id](deviceinformation_id.md) for this object as a string.
 
 ### -field AssociationEndpointProtocol:9
 
-TBD
+Specifies that the [DeviceInformation](deviceinformation.md) object represents a protocol through which association endpoints (AEPs) can be discovered. You can scope an association endpoint discovery to specific protocols by using the protocol ID. For example, the following selector scopes discovery to Bluetooth LE or Bluetooth Classic.
+
+`System.Devices.Aep.ProtocolId:="{e0cbf06c-cd8b-4647-bb8a-263b43f0f974}"` or `DEVPKEY_Aep_ProtocolId:="{e0cbf06c-cd8b-4647-bb8a-263b43f0f974}"`.
+
+System.Devices.Aep.ProtocolId is the protocol's name in propsys; and DEVPKEY_Aep_ProtocolId is the Win32 DEVPKEY.
+
+Here's a representative example of what enumerating a protocol looks like, and how it matches up to the AEP properties (with annotations inside square brackets).
+
+```console
+> pairtool /enum-protocols
+...
+Protocol ID:                Bluetooth [DEVPKEY_Aep_ProviderName]
+Protocol Provider Name:     Bluetooth
+Protocol Name:              Bluetooth Classic
+Universal Protocol ID:      {e0cbf06c-cd8b-4647-bb8a-263b43f0f974} [DEVPKEY_Aep_ProtocolId // <propertyDescription name="System.Devices.Aep.ProtocolId" formatID="{3B2CE006-5E61-4FDE-BAB8-9B8AAC9B26DF}" propID="5">]
+Protocol Provider Class ID: {4aa383d6-337a-43d3-a3fa-c14b26004130}
+
+Protocol ID:                BluetoothLE [DEVPKEY_Aep_ProviderName]
+Protocol Provider Name:     BluetoothLE
+Protocol Name:              Bluetooth Low Energy
+Universal Protocol ID:      {bb7bb05e-5972-42b5-94fc-76eaa7084d49} [DEVPKEY_Aep_ProtocolId]
+Protocol Provider Class ID: {0829c308-d361-49f4-828b-506d552029ef} 
+...
+> pairtool /enum-endpoints
+
+BluetoothLE#BluetoothLEdc:46:28:6a:16:01-20:4c:03:45:07:ca
+  1)DEVPKEY_Aep_ContainerId [SYS] (null) DEVPROP_TYPE_GUID 16 {72888bff-567a-54f9-861a-73a3f2df469c} 
+...
+  30)DEVPKEY_Aep_ProviderName [SYS] (null) DEVPROP_TYPE_STRING 24 "BluetoothLE"
+  33)DEVPKEY_Aep_ProtocolId [SYS] (null) DEVPROP_TYPE_GUID 16 {bb7bb05e-5972-42b5-94fc-76eaa7084d49}
+```
 
 ## -remarks
 

windows.devices.enumeration/devicepairingaddpairingsetmemberstatus.md

@@ -12,29 +12,29 @@ public enum DevicePairingAddPairingSetMemberStatus
 
 ## -description
 
-Defines constants that specify TBD. For more info, and code examples, see [Pairing a set with the DeviceInformationPairing.Custom property](/windows/uwp/devices-sensors/pairing-a-set).
+Defines constants that specify a status value describing the result of adding member(s) to a pairing set. For more info, and code examples, see [Pairing a set with the DeviceInformationPairing.Custom property](/windows/uwp/devices-sensors/pairing-a-set). See [DevicePairingSetMembersRequestedEventArgs.Status](./devicepairingsetmembersrequestedeventargs_status.md).
 
 ## -enum-fields
 
 ### -field AddedToSet: 0
 
-Specifies that the device was successfully added to the set.
+Specifies that set member(s) were added successfully to the set. This status applies to a call to [DeviceInformationCustomPairing.AddPairingSetMember](./deviceinformationcustompairing_addpairingsetmember_1277113744.md), and indicates that you can expect *the successfully added set member(s)* to be in the [DevicePairingSetMembersRequestedEventArgs.PairingSetMembers](./devicepairingsetmembersrequestedeventargs_pairingsetmembers.md) vector.
 
 ### -field CouldNotBeAddedToSet: 1
 
-Specifies that we failed to add set member(s).
+Specifies that set member(s) couldn't be added to the set. This status applies to a call to [DeviceInformationCustomPairing.AddPairingSetMember](./deviceinformationcustompairing_addpairingsetmember_1277113744.md), and indicates that you can expect *the set member(s) that couldn't be added* to be in the [DevicePairingSetMembersRequestedEventArgs.PairingSetMembers](./devicepairingsetmembersrequestedeventargs_pairingsetmembers.md) vector.
 
 ### -field SetDiscoveryNotAttemptedByProtocol: 2
 
-Specifies TBD
+Specifies that the protocol didn't attempt to discover set members. The protocol probably doesn't support it.
 
 ### -field SetDiscoveryCompletedByProtocol: 3
 
-Specifies TBD
+Specifies that the protocol successfully enumerated all set members. No further discovery will happen.
 
 ### -field SetDiscoveryPartiallyCompletedByProtocol: 4
 
-Specifies TBD
+Specifies that the protocol discovered some set members, but not all of them. No further discovery will happen.
 
 ### -field Failed: 5
 
@@ -44,4 +44,4 @@ Specifies that an unknown failure occurred, for which we have no mapping.
 
 ## -see-also
 
-[Pairing a set with the DeviceInformationPairing.Custom property](/windows/uwp/devices-sensors/pairing-a-set)
+[DevicePairingSetMembersRequestedEventArgs.Status](./devicepairingsetmembersrequestedeventargs_status.md), [Pairing a set with the DeviceInformationPairing.Custom property](/windows/uwp/devices-sensors/pairing-a-set)

windows.devices.enumeration/devicepairingkinds.md

@@ -11,7 +11,8 @@ public enum Windows.Devices.Enumeration.DevicePairingKinds : uint
 # DevicePairingKinds
 
 ## -description
-Indicates the kinds of pairing supported by your application or requested by the system. As an input value, use this value to indicate what kinds of pairing your application supports. When this datatype is received as an output value, it indicates the kind of pairing requested by the system. In this case, your code will need to respond accordingly.
+
+Defines constants that specify kinds of pairing supported by your application or requested by the system. As an input value, use this value to indicate what kinds of pairing your application supports. When this datatype is received as an output value, it indicates the kind of pairing requested by the system; in that case, your code will need to respond accordingly.
 
 ## -enum-fields
 
@@ -34,11 +35,10 @@ The application must display the given PIN to the user and ask the user to confi
 The application must request a user name and password from the user. With a value of **ProvidePasswordCredential**, call [AcceptWithPasswordCredential](devicepairingrequestedeventargs_acceptwithpasswordcredential_1073078053.md) from the event args of the [PairingRequested](deviceinformationcustompairing_pairingrequested.md) event handler to accept the pairing. Pass in the [PasswordCredential](../windows.security.credentials/passwordcredential.md) that encapsulates the user name and password as a parameter.
 
 ### -field ProvideAddress:32
-
-TBD
+Specifies that your application must provide an address from the device. This is typically used for directed discovery over a network protocol such as IPP or UPnP, where the application already knows the IP/address/URL of the device. With a value of **ProvideAddress**, you should call [DevicePairingRequestedEventArgs.AcceptWithAddress](./devicepairingrequestedeventargs_acceptwithaddress_1238468511.md) on the event args of the [DeviceInformationCustomPairing.PairingRequested](/uwp/api/windows.devices.enumeration.deviceinformationcustompairing.pairingrequested) event handler, if you want the pairing to complete. Pass in the address as a parameter.
 
 ## -remarks
-This value is a collection of flags. It is possible to have multiple values set for a single pairing action.
+This value is a collection of flags. It's possible to have multiple values set for a single pairing action.
 
 ### Version history
 

windows.devices.enumeration/devicepairingrequestedeventargs_acceptwithaddress_1238468511.md

@@ -18,7 +18,7 @@ Accepts a [PairingRequested](deviceinformationcustompairing_pairingrequested.md)
 
 ### -param address
 
-TBD
+Your app must provide an address from the device. This is typically used for directed discovery over a network protocol such as IPP or UPnP, where the application already knows the IP/address/URL of the device. You should call **AcceptWithAddress** if you want the pairing to complete. Pass in the address as a parameter.
 
 ## -remarks
 

windows.devices.enumeration/devicepairingsetmembersrequestedeventargs.md

@@ -12,9 +12,11 @@ public sealed class DevicePairingSetMembersRequestedEventArgs
 
 ## -description
 
-TBD
+Event arguments passed to your handler for the [DeviceInformationCustomPairing.PairingSetMembersRequested](./deviceinformationcustompairing_pairingsetmembersrequested.md) event, which is raised when the member(s) of a pairing set have been requested.
 
-This is the type of the event args for the [DeviceInformationCustomPairing.PairingSetMembersRequested](./deviceinformationcustompairing_pairingsetmembersrequested.md) event. For more info, and code examples, see [Pairing a set with the DeviceInformationPairing.Custom property](/windows/uwp/devices-sensors/pairing-a-set).
+**DevicePairingSetMembersRequestedEventArgs** contains: a status indicating success or failure; a vector of the devices/endpoints that were added to the set, or that failed to be added to the set, depending on that status; and info about the parent device.
+
+For more info, and code examples, see [Pairing a set with the DeviceInformationPairing.Custom property](/windows/uwp/devices-sensors/pairing-a-set).
 
 ## -remarks