From c69a12096cadb46cc43a97c3966900916a29cc21 Mon Sep 17 00:00:00 2001
From: James Westman <james@jwestman.net>
Date: Tue, 13 Jun 2023 20:41:41 -0500
Subject: [PATCH] docs: Update bindings docs

---
 docs/reference/objects.rst |  2 +-
 docs/reference/values.rst  | 50 ++++++++++++++++----------------------
 2 files changed, 22 insertions(+), 30 deletions(-)

diff --git a/docs/reference/objects.rst b/docs/reference/objects.rst
index 8acbb32..fe4d1a7 100644
--- a/docs/reference/objects.rst
+++ b/docs/reference/objects.rst
@@ -58,7 +58,7 @@ Properties
 
 .. rst-class:: grammar-block
 
-   Property = <name::ref:`IDENT<Syntax IDENT>`> ':' ( :ref:`PropertyBinding<Syntax PropertyBinding>` | :ref:`Binding<Syntax Binding>` | :ref:`ObjectValue<Syntax ObjectValue>` | :ref:`Value<Syntax Value>` ) ';'
+   Property = <name::ref:`IDENT<Syntax IDENT>`> ':' ( :ref:`Binding<Syntax Binding>` | :ref:`ObjectValue<Syntax ObjectValue>` | :ref:`Value<Syntax Value>` ) ';'
 
 Properties specify the details of each object, like a label's text, an image's icon name, or the margins on a container.
 
diff --git a/docs/reference/values.rst b/docs/reference/values.rst
index 9c0a09f..035408f 100644
--- a/docs/reference/values.rst
+++ b/docs/reference/values.rst
@@ -102,34 +102,6 @@ Use ``C_("context", "...")`` to add a *message context* to a string to disambigu
    }
 
 
-.. _Syntax PropertyBinding:
-
-Property Bindings
------------------
-
-.. rst-class:: grammar-block
-
-   PropertyBinding = 'bind-property' <source::ref:`IDENT<Syntax IDENT>`> '.' <property::ref:`IDENT<Syntax IDENT>`> (PropertyBindingFlag)*
-   PropertyBindingFlag = 'inverted' | 'bidirectional' | 'no-sync-create'
-
-Bindings keep a property updated as another property changes. They can be used to keep the UI in sync with application data, or to connect two parts of the UI.
-
-Example
-~~~~~~~
-
-.. code-block:: blueprintui
-
-   /* Use property bindings to show a label when a switch
-    * is active, without any application code */
-
-   Switch advanced_feature {}
-
-   Label warning {
-     visible: bind-property advanced_feature.active;
-     label: _("This is an advanced feature. Use with caution!");
-   }
-
-
 .. _Syntax Binding:
 
 Expression Bindings
@@ -139,7 +111,27 @@ Expression Bindings
 
    Binding = 'bind' :ref:`Expression<Syntax Expression>`
 
-Expression bindings serve the same purpose as property bindings, but are more powerful. They can call application code to compute the value of a property, and they can do multi-step property lookups. See :ref:`the expressions page<Syntax Expression>`.
+Bindings keep a property updated as other properties change. They can be used to keep the UI in sync with application data, or to connect two parts of the UI.
+
+The simplest bindings connect to a property of another object in the blueprint. When that other property changes, the bound property updates as well. More advanced bindings can do multi-step property lookups and can even call application code to compute values. See :ref:`the expressions page<Syntax Expression>`.
+
+Example
+~~~~~~~
+
+.. code-block:: blueprintui
+
+   /* Use bindings to show a label when a switch
+    * is active, without any application code */
+
+   Switch advanced_feature {}
+
+   Label warning {
+     visible: bind-property advanced_feature.active;
+     label: _("This is an advanced feature. Use with caution!");
+   }
+
+.. code-block: blueprintui
+
 
 
 .. _Syntax ObjectValue: