[skeleton] Add Thing config table to readme; minor improvements (#2692)

* [skeleton] Add Thing config table to readme; minor improvements

- put each sentence in a seperate line
- add note that only PNG images are supported. See https://github.com/openhab/openhab-addons/pull/11116#discussion_r775838188
- add examples to "Supported Things"
- add RW column to example Channel table
- add advanced and default config value
- add note that textual config examples are mandatory
- make .sitemap example optional (see small internal discussion)
- put emphasis on initialize() shall return quickly
- add note about logging to INFO
- fix compiler warning
- Add default config value for initialization

Signed-off-by: Fabian Wolter <github@fabian-wolter.de>

tools/archetype/binding/src/main/resources/archetype-resources/README.md

@@ -2,21 +2,30 @@
 
 _Give some details about what this binding is meant for - a protocol, system, specific device._
 
-_If possible, provide some resources like pictures, a video, etc. to give an impression of what can be done with this binding. You can place such resources into a `doc` folder next to this README.md._
+_If possible, provide some resources like pictures (only PNG is supported currently), a video, etc. to give an impression of what can be done with this binding._
+_You can place such resources into a `doc` folder next to this README.md._
+
+_Put each sentence in a separate line to improve readability of diffs._
 
 #[[##]]# Supported Things
 
-_Please describe the different supported things / devices within this section._
+_Please describe the different supported things / devices including their ThingTypeUID within this section._
 _Which different types are supported, which models were tested etc.?_
 _Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
 
+- `bridge`: Short description of the Bridge, if any
+- `sample`: Short description of the Thing with the ThingTypeUID `sample`
+
 #[[##]]# Discovery
 
-_Describe the available auto-discovery features here. Mention for what it works and what needs to be kept in mind when using it._
+_Describe the available auto-discovery features here._
+_Mention for what it works and what needs to be kept in mind when using it._
 
 #[[##]]# Binding Configuration
 
-_If your binding requires or supports general configuration settings, please create a folder ```cfg``` and place the configuration file ```<bindingId>.cfg``` inside it. In this section, you should link to this file and provide some information about the options. The file could e.g. look like:_
+_If your binding requires or supports general configuration settings, please create a folder ```cfg``` and place the configuration file ```<bindingId>.cfg``` inside it._
+_In this section, you should link to this file and provide some information about the options._
+_The file could e.g. look like:_
 
 ```
 # Configuration for the ${bindingIdCamelCase} Binding
@@ -33,23 +42,34 @@ _If your binding does not offer any generic configurations, you can remove this
 
 #[[##]]# Thing Configuration
 
-_Describe what is needed to manually configure a thing, either through the UI or via a thing-file. This should be mainly about its mandatory and optional configuration parameters. A short example entry for a thing file can help!_
+_Describe what is needed to manually configure a thing, either through the UI or via a thing-file._
+_This should be mainly about its mandatory and optional configuration parameters._
 
 _Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
 
+#[[###]]# `sample` Thing Configuration
+
+| Name            | Type    | Description                           | Default | Required | Advanced |
+|-----------------|---------|---------------------------------------|---------|----------|----------|
+| hostname        | text    | Hostname or IP address of the device  | N/A     | yes      | no       |
+| password        | text    | Password to access the device         | N/A     | yes      | no       |
+| refreshInterval | integer | Interval the device is polled in sec. | 600     | no       | yes      |
+
 #[[##]]# Channels
 
 _Here you should provide information about available channel types, what their meaning is and how they can be used._
 
 _Note that it is planned to generate some part of this based on the XML files within ```src/main/resources/OH-INF/thing``` of your binding._
 
-| channel  | type   | description                  |
+| Channel | Type   | Read/Write | Description                 |
-|----------|--------|------------------------------|
+|---------|--------|------------|-----------------------------|
-| control  | Switch | This is the control channel  |
+| control | Switch | RW         | This is the control channel |
 
 #[[##]]# Full Example
 
-_Provide a full usage example based on textual configuration files (*.things, *.items, *.sitemap)._
+_Provide a full usage example based on textual configuration files._
+_*.things, *.items examples are mandatory as textual configuration is well used by many users._
+_*.sitemap examples are optional._
 
 #[[##]]# Any custom content here!
 

tools/archetype/binding/src/main/resources/archetype-resources/src/main/java/internal/__bindingIdCamelCase__Configuration.java

@@ -15,17 +15,20 @@
  */
 package ${package}.internal;
 
+import org.eclipse.jdt.annotation.NonNullByDefault;
+
 /**
  * The {@link ${bindingIdCamelCase}Configuration} class contains fields mapping thing configuration parameters.
  *
  * @author ${author} - Initial contribution
  */
+@NonNullByDefault
 public class ${bindingIdCamelCase}Configuration {
 
     /**
      * Sample configuration parameters. Replace with your own.
      */
-    public String hostname;
+    public String hostname = "";
-    public String password;
+    public String password = "";
-    public int refreshInterval;
+    public int refreshInterval = 600;
 }

tools/archetype/binding/src/main/resources/archetype-resources/src/main/java/internal/__bindingIdCamelCase__Handler.java

@@ -66,9 +66,10 @@ public class ${bindingIdCamelCase}Handler extends BaseThingHandler {
         config = getConfigAs(${bindingIdCamelCase}Configuration.class);
 
         // TODO: Initialize the handler.
-        // The framework requires you to return from this method quickly. Also, before leaving this method a thing
+        // The framework requires you to return from this method quickly, i.e. any network access must be done in
-        // status from one of ONLINE, OFFLINE or UNKNOWN must be set. This might already be the real thing status in
+        // the background initialization below.
-        // case you can decide it directly.
+        // Also, before leaving this method a thing status from one of ONLINE, OFFLINE or UNKNOWN must be set. This
+        // might already be the real thing status in case you can decide it directly.
         // In case you can not decide the thing status directly (e.g. for long running connection handshake using WAN
         // access or similar) you should set status UNKNOWN here and then decide the real status asynchronously in the
         // background.
@@ -93,6 +94,9 @@ public class ${bindingIdCamelCase}Handler extends BaseThingHandler {
         // logger.trace("Example trace message");
         // logger.debug("Example debug message");
         // logger.warn("Example warn message");
+        //
+        // Logging to INFO should be avoided normally.
+        // See https://www.openhab.org/docs/developer/guidelines.html#f-logging
 
         // Note: When initialization can NOT be done set the status with more details for further
         // analysis. See also class ThingStatusDetail for all available status details.

tools/archetype/binding/src/main/resources/archetype-resources/src/main/resources/OH-INF/thing/thing-types.xml

@@ -28,11 +28,13 @@
 			<parameter name="password" type="text" required="true">
 				<context>password</context>
 				<label>Password</label>
-				<description>Passwort to access the device</description>
+				<description>Password to access the device</description>
 			</parameter>
 			<parameter name="refreshInterval" type="integer" unit="s" min="1">
 				<label>Refresh Interval</label>
 				<description>Interval the device is polled in sec.</description>
+				<default>600</default>
+				<advanced>true</advanced>
 			</parameter>
 		</config-description>
 	</thing-type>