From d3ee790da1826529e3d025d919f5c3608d029562 Mon Sep 17 00:00:00 2001
From: Roel Standaert <roel@emweb.be>
Date: Fri, 11 Dec 2020 13:51:52 +0100
Subject: [PATCH] Discourage the use of setId(), encourage the use of
 setObjectName()

---
 src/Wt/WObject.h | 9 +++++++--
 src/Wt/WWidget.h | 7 +++++++
 2 files changed, 14 insertions(+), 2 deletions(-)

diff --git a/src/Wt/WObject.h b/src/Wt/WObject.h
index 3a9558f587..836adaed8b 100644
--- a/src/Wt/WObject.h
+++ b/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).
    */
diff --git a/src/Wt/WWidget.h b/src/Wt/WWidget.h
index dce3b8b3bf..ac753d1593 100644
--- a/src/Wt/WWidget.h
+++ b/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;