Add developer documentation for CoAP adapter

Also applied small fixes to existing developer documentation.

site/documentation/content/dev-guide/_index.md

@@ -7,4 +7,4 @@ pre = '<i class="fas fa-tools"></i> '
 
 # Developer Guide
 
-Learn how to build Eclipse Hono&trade; and how to integrate your custom components with it. 
+Learn how to build Eclipse Hono&trade; and how to integrate your custom components with it.

site/documentation/content/dev-guide/amqp_adapter_client.md

@@ -3,8 +3,8 @@ title = "AMQP Adapter Client for Java"
 weight = 390
 +++
 
-Eclipse Hono™ comes with a Java client for the AMQP adapter. It is intended for the implementation of 
-(prototype) devices, (protocol) gateways or (end-to-end) tests. The client is based on Eclipse Vert.x.
+Eclipse Hono™ comes with a Java client for the AMQP adapter. It is intended for the implementation of
+(prototype) devices, (protocol) gateways and/or (end-to-end) tests. The client is based on Eclipse Vert.x.
 
 The client is represented by the [AmqpAdapterClient](https://github.com/eclipse-hono/hono/blob/master/clients/device-amqp/src/main/java/org/eclipse/hono/client/device/amqp/AmqpAdapterClient.java)
 class in the *hono-client-device-amqp* module.

site/documentation/content/dev-guide/coap_adapter.md

@@ -0,0 +1,17 @@
++++
+title = "Considerations for extending the CoAP Adapter"
+weight = 398
++++
+
+This page provides some hints worth considering when extending the CoAP protocol adapter's functionality.
+
+## Option Numbers
+
+The CoAP adapter uses several of the standard options defined by [RFC 7252](https://www.rfc-editor.org/rfc/rfc7252.html).
+Unlike HTTP header fields which are simple strings, the options used in CoAP request and response messages
+are defined by means of integer numbers. The assignment and registration of option numbers is defined in
+[RFC 7252, Section 12.2](https://www.rfc-editor.org/rfc/rfc7252.html#section-12.2). In particular, the RFC reserves
+the number range 65000-65535 for experimental use.
+
+When adding new Hono specific options to the CoAP adapter, developers are encouraged to use numbers from the 65175-65349
+range as [discussed and agreed with the Eclipse Californium project](https://github.com/eclipse-hono/hono/issues/3499#issuecomment-1602478483).

site/documentation/content/dev-guide/java_client_consumer.md

@@ -1,46 +1,50 @@
 +++
 title = "Consuming Messages from Java"
-weight = 390
+weight = 397
 +++
 
-To illustrate how Eclipse Hono™ can be integrated with Java code, a simple application is provided that consumes telemetry and event data 
-for devices belonging to the default tenant. 
+To illustrate how Eclipse Hono™ can be integrated with Java code, a simple application is provided that
+consumes telemetry and event data for devices belonging to the default tenant.
 
-It also includes support for Command and Control:
+It also includes support for Command & Control:
 
-if indicated by a received downstream message that contains a `ttd` value (refer to [Device notifications]({{< relref "concepts/device-notifications/index.md" >}}) for details) it tries to send a command to the device.
-If the value of `ttd` indicates that the device stays connected for an unlimited time (`ttd == -1`), the application will periodically repeat to send a command until
-notified the device is disconnected again (`ttd == 0`).
+* If indicated by a received downstream message that contains a `ttd` value (refer to
+  [Device notifications]({{< relref "concepts/device-notifications/index.md" >}}) for details) it tries to send a command
+  to the device.
+* If the value of `ttd` indicates that the device stays connected for an unlimited time (`ttd == -1`), the application will
+  periodically repeat to send a command until notified the device is disconnected again (`ttd == 0`).
 
-This application shall serve as a blueprint to integrate your existing java source code with Hono. 
-Its code is found in the [example](https://github.com/eclipse-hono/hono/tree/master/examples) module in the package [org.eclipse.hono.vertx.example](https://github.com/eclipse-hono/hono/tree/master/examples/hono-client-examples/src/main/java/org/eclipse/hono/vertx/example).
+This application shall serve as a blueprint to integrate your existing Java source code with Hono.
+Its code is found in the [example](https://github.com/eclipse-hono/hono/tree/master/examples) module in the package
+[org.eclipse.hono.vertx.example](https://github.com/eclipse-hono/hono/tree/master/examples/hono-client-examples/src/main/java/org/eclipse/hono/vertx/example).
 
-The provided classes are kept as simple as possible (in the tradition of a classical "Hello World" implementation) while still
+The provided classes are kept as simple as possible (in the tradition of a classical *Hello World* implementation) while still
 covering the most relevant messaging patterns (downstream and upstream messages).
 For this purpose they make use of simple constant definitions and deal with exceptions as rarely as possible.
 You may want to change the level of detail that should be logged to the console by editing the contained `resources/logback.xml` file.
 
-Please refer to the javadoc of the classes for details.
+Please refer to the JavaDoc of the classes for details.
 
 {{% notice info %}}
 Note that production ready code likely has to think more about error handling and logging than this simple blueprint.
 {{% /notice %}}
 
-## Configure the example
+## Configure the Example
 
-For simplicity, all configurations are defined as Java constants inside the class [HonoExampleConstants](https://github.com/eclipse-hono/hono/blob/master/examples/hono-client-examples/src/main/java/org/eclipse/hono/vertx/example/base/HonoExampleConstants.java).
+For simplicity, all configurations are defined as Java constants inside the class
+[HonoExampleConstants](https://github.com/eclipse-hono/hono/blob/master/examples/hono-client-examples/src/main/java/org/eclipse/hono/vertx/example/base/HonoExampleConstants.java).
 
 If you have Hono running in Docker under `localhost`, the example should work out of the box.
 
 Some configuration values can be overridden by providing them as property to the application.
 
 This includes the `host` and the `port` of the AMQP network.
-In the standard setup of Hono they should be configured to the [qdrouter](https://qpid.apache.org/components/dispatch-router/index.html) from the Apache Qpid project.
-In production scenarios this might be a large setup of AMQP routers, brokers, etc.
+In the standard setup of Hono they should be configured to the [qdrouter](https://qpid.apache.org/components/dispatch-router/index.html)
+from the Apache Qpid project. In production scenarios this might be a large setup of AMQP routers, brokers, etc.
 
 Please refer to the class `HonoExampleConstants` to find out which part of the application can be configured by properties.
 
-## Run the example
+## Run the Example
 
 The application waits for messages until you press any key or kill it.
 
@@ -52,7 +56,7 @@ mvn clean package
 mvn exec:java -Dexec.mainClass=org.eclipse.hono.vertx.example.HonoExampleApplication
 ~~~
 
-or --- if e.g. the host of the AMQP network should be changed --- 
+or (if e.g. the host of the AMQP network should be changed):
 
 ~~~sh
 mvn exec:java -Dexec.mainClass=org.eclipse.hono.vertx.example.HonoExampleApplication -Dconsumer.host=192.168.99.100
@@ -63,30 +67,34 @@ mvn exec:java -Dexec.mainClass=org.eclipse.hono.vertx.example.HonoExampleApplica
 
 Depending on the logger configuration, all received downstream messages are printed to the console.
 
-Please note that consumers do not connect with Hono directly, but rather with an AMQP router network. 
+Please note that consumers do not connect with Hono directly, but rather with an AMQP router network.
 
 ### Command and Control
 
-By using a helper class provided by Hono, a callback in the application code is invoked when a downstream message was received
-that signals the device will stay connected to the protocol adapter for some time (see [Device notifications]({{< relref "concepts/device-notifications/index.md" >}}) for details).
+By using a helper class provided by Hono, a callback in the application code is invoked when a downstream
+message was received that signals the device will stay connected to the protocol adapter for some time (see
+[Device notifications]({{< relref "concepts/device-notifications/index.md" >}}) for details).
 
-Inside this callback an arbitrary simple command is sent down to the device (once or periodically) and the response is logged to the console.
+Inside this callback an arbitrary simple command is sent down to the device (once or periodically) and the
+response is logged to the console.
 
-### Encryption of communication 
+### Encryption of Communication 
 
 For the encrypted communication with Hono, the necessary truststore is already installed and used by the Hono client.
 
-If you want to integrate the code with your own software, please copy the provided truststore (`hono/demo-certs/certs/trusted-certs.pem`) 
-from the Hono project to the `resources` directory of your project
+If you want to integrate the code with your own software, please copy the provided truststore
+(`hono/demo-certs/certs/trusted-certs.pem`) from the Hono project to the `resources` directory of your project
 and adopt the code pointing to the file location.
 
 ### Kafka based Messaging
 
-To use Kafka based messaging instead of an AMQP network, set the property `kafka` to `true` provide the host and port of a bootstrap server:
+To use Kafka based messaging instead of an AMQP network, set the property `kafka` to `true` provide the host and port
+of a bootstrap server:
 
 ~~~sh
 mvn exec:java -Dexec.mainClass=org.eclipse.hono.vertx.example.HonoExampleApplication -Dconsumer.host=192.168.99.100 -Dconsumer.port=9092 -Dkafka=true
 ~~~
 
-Additional properties for the Kafka producers and consumers can be added in the code, for example to enable encrypted communication. 
-For the available configuration options refer to the [Kafka documentation]()https://kafka.apache.org/documentation/#configuration. 
+Additional properties for the Kafka producers and consumers can be added in the code, for example to enable
+encrypted communication. For the available configuration options refer to the
+[Kafka documentation](https://kafka.apache.org/documentation/#configuration).