No, I can’t replicate it…
I tried some quick tests in 2 different systems and using /etc/openhab2/services/mqtt.cfg:
broker-name.url=tcp://localhost:1883
broker-name.clientId=openhab2s
broker-name.user=openhab
broker-name.pwd=password
My OH2 (Snapshot 917) with the MQTT Binding (v 1.10.0.201705130111) works fine without any problems…
2017-05-13 22:09:12.103 [INFO ] [penhab.io.transport.mqtt.MqttService] - MQTT Service initialization completed.
2017-05-13 22:09:12.104 [INFO ] [t.mqtt.internal.MqttBrokerConnection] - Starting MQTT broker connection 'broker-name'
2017-05-13 22:09:12.104 [DEBUG] [org.openhab.io.transport.mqtt ] - BundleEvent STARTED - org.openhab.io.transport.mqtt
2017-05-13 22:09:12.105 [DEBUG] [t.mqtt.internal.MqttBrokerConnection] - Creating new client for 'tcp://localhost:1883' using id 'openhab2s' and file store '/var/lib/openhab2/tmp/broker-name'
So… I don’t know what was wrong with Andrew’s configurations… but it seems that it wasn’t the non-alphanumeric character in the broker alias… As a result… no need to update the documentation for now.
I will try some more tests (also on OH2 Release Build) and some more complex item configs and will report back.