[documentation] clarification of representation property

concepts/discovery.md

@@ -27,8 +27,9 @@ Each discovery result also has a timestamp when it was added to or updated in th
 Discovery results can either be ignored or approved, where in the latter case a Thing is created for them and they become available in the application. 
 If an entry is ignored, it will be hidden in the inbox without creating a Thing for it. 
 
-openHAB offers a service to automatically ignore discovery results in the inbox, whenever a Thing is created manually, that represents the same Thing, as the respective discovery result would create. 
-This Thing would either have the same Thing UID or the value of its representation property is equal to the representation property's value in the discovery result.
+openHAB offers a service to automatically ignore discovery results in the inbox, whenever a) a Thing has been created manually, that represents the same Thing as the respective discovery result would create, or b) whenever a Thing has been discovered separately by two alternate discovery services e.g. by mDNS and UPnP.
+This Thing would either have the same Thing UID or the value of its `representation property` is equal to the representation property value of the discovery result.
+For a manually created Thing, its representation property may be either a `property` or a `configuration parameter` of the Thing.
 This service is enabled by default but can be disabled by setting `org.eclipse.smarthome.inbox:autoIgnore=false`. 
 
 ### Auto Approve

developers/bindings/index.md

@@ -660,7 +660,7 @@ The following table gives an overview about the main parts of a `DiscoveryResult
 | `bridgeUID` | If the discovered thing belongs to a bridge, the `bridgeUID` contains the UID of that bridge.
 | `properties` | The `properties` of a `DiscoveryResult` contain the configuration for the newly created thing.
 | `label` | The human readable representation of the discovery result. Do not put IP/MAC addresses or similar into the label but use the special `representationProperty` instead. |
-| `representationProperty` | The name of one of the properties which discriminates the discovery result best against other results of the same type. Typically this is a serial number, IP or MAC address. The representationProperty often matches a configuration parameter and is also explicitly given in the thing-type definition. |
+| `representationProperty` | The name of one of the properties or configuration parameters, which discriminates the discovery result against a) other results of the same type, or b) already existing manually created Things. Typically this is a serial number, IP or MAC address. The representationProperty must be declared in the `thing-types.xml` definition. When comparing the representation property of a discovery result with an existing Thing, the framework checks for a match in its `properties` and also its `configuration parameters`. |
 
 To simplify the implementation of custom discovery services, an abstract base class `AbstractDiscoveryService` implements the `DiscoveryService` and just needs to be extended.
 Subclasses of `AbstractDiscoveryService` do not need to handle the `DiscoveryListeners` themselves, they can use the methods `thingDiscovered` and `thingRemoved` to notify the registered listeners.

developers/bindings/thing-xml.md

@@ -488,7 +488,7 @@ In contrast to the properties defined in the 'ThingType' definitions the thing h
 ### Representation Property
 
 A thing type can contain a so-called `representation property`.
-This optional property contains the _name_ of a property whose value can be used to uniquely identify a device.
+This optional property contains the _**name**_ of a property whose value can be used to uniquely identify a device.
 The `thingUID` cannot be used for this purpose because there can be more than one thing for the same device.
 
 Each physical device normally has some kind of a technical identifier which is unique.
@@ -514,12 +514,30 @@ The name of the `representation property` identifies a property that is added to
 
 ### Representation Property and Discovery
 
-The representation property is being used to auto-ignore discovery results of devices that already have a corresponding thing.
-This happens if a device is being added manually.
-If the new thing is going online, the auto-ignore service of the inbox checks if the inbox already contains a discovery result of the same type where the value of its `representation property` is identical to the value of the `representation property` of the newly added thing.
-If this is the case, the result in the inbox is automatically set to ignored.
-Note that this result is automatically removed when the manual added thing is eventually removed.
-A new discovery would then automatically find this device again and add it to the inbox properly.
+The representation property is used to auto-ignore discovery results of things that already exist in the system.
+This can happen a) if a thing has been created manually, or b) it has been discovered separately by two mechanisms e.g. by mDNS, and by NetBios, or UPnP.
+If the new thing goes online, the auto-ignore service of the inbox checks if the inbox already contains a discovery result of the same type where the value of its `representation property` is identical to the value of the `representation property` of the newly added thing.
+If this is the case, the thing in the inbox is automatically set to ignored.
+Note that this thing is automatically removed when the manually added thing is eventually removed.
+A new discovery would then automatically find this thing again and add it to the inbox properly.
+
+When the auto-ignore service checks the `representation property`, it first checks if the thing has `property` of the same name, and then it checks if the thing has a `configuration parameter` of the same name.
+If the latter is used, then the respective `parameter` should be described in the `configuration-description` part of the XML:
+
+```xml
+    <thing-type id="thingTypeId">
+        ...
+        <representation-property>serialNumber</representation-property>
+        ...
+    		<config-description>
+  			  <parameter name="serialNumber" type="text">
+		  		  <label>Serial Number</label>
+			  	  <description>The Serial Number</description>
+  			  </parameter>
+    		</config-description>
+        ...
+    </thing-type>
+```
 
 ## Formatting Labels and Descriptions