Discourage the use of setId(), encourage the use of setObjectName()

src/Wt/WObject.h

@@ -166,8 +166,13 @@ class WT_API WObject : public Wt::Core::observable
    * in the DOM, and does not need to be unique. It will usually
    * reflect the widget type or role.
    *
-   * The object name is present in the DOM in the 'data-object-name'
-   * attribute.
+   * If a WWidget has an object name, the object name is reflected
+   * in the `data-object-name` attribute. You can use this to find
+   * widgets in JavaScript (e.g. for automated testing) using:
+   *
+   * ```
+   * document.querySelector('*[data-object-name="yourObjectNameHere"]')
+   * ```
    *
    * The default object name is empty (no object name).
    */

src/Wt/WWidget.h

@@ -947,6 +947,13 @@ class WT_API WWidget : public WObject
    * letters, digits ([0-9]), hyphens ("-"), underscores ("_"), colons (":"),
    * and periods (".").
    *
+   * \warning We recommend that you leave the id of a widget unchanged. %Wt
+   * uses the id to identify widgets in the JavaScript it generates,
+   * and this can often leads to bugs. If you do change the id, **only** change
+   * the id right after widget construction. However, usually
+   * there's a more preferable alternative, like setting the object name
+   * (WObject::setObjectName), or adding style classes (WWidget::addStyleClass).
+   *
    * \sa WObject::id()
    */
   virtual void setId(const std::string& id) = 0;