You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@causeway.apache.org by da...@apache.org on 2023/06/01 22:03:40 UTC

[causeway] 01/01: CAUSEWAY-2485: polishes demoapp

This is an automated email from the ASF dual-hosted git repository.

danhaywood pushed a commit to branch CAUSEWAY-2485
in repository https://gitbox.apache.org/repos/asf/causeway.git

commit 822d66988920ae85ec13f6757b7d339b6f8be12a
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Thu Jun 1 23:03:10 2023 +0100

    CAUSEWAY-2485: polishes demoapp
---
 .../demoapp/dom/domain/_entities/DemoEntity.java   | 26 --------
 ...andPublishingEntity_changeNameNotPublished.java |  7 ++
 ...ommandPublishingEntity_changeNamePublished.java |  8 ++-
 ...nCommandPublishingEntity_publishedCommands.java |  5 +-
 .../ActionCommandPublishingPage-description.adoc   |  7 +-
 ...mmandPublishingPage_changeNameNotPublished.java |  7 ++
 ...nCommandPublishingPage_changeNamePublished.java |  7 ++
 .../ActionDomainEventPage_updateText.java          |  4 ++
 ...tionDomainEventPage_updateTextNotAnnotated.java |  4 ++
 ...ionPublishingEntity_changeNameNotPublished.java |  6 +-
 ...cutionPublishingEntity_changeNamePublished.java |  5 +-
 .../ActionExecutionPublishingPage-description.adoc | 17 +++--
 .../ActionExecutionPublishingPage.layout.xml       | 26 ++++----
 ...utionPublishingPage_changeNameNotPublished.java |  7 ++
 ...xecutionPublishingPage_changeNamePublished.java |  7 ++
 ...nExecutionPublishingPage_changeNameWrapped.java | 12 +++-
 .../semantics/ActionSemanticsPage-description.adoc |  2 +-
 .../typeOf/ActionTypeOfPage-description.adoc       | 13 ++--
 .../PropertyCommandPublishingEntity.java           | 16 +++--
 .../PropertyCommandPublishingEntity.layout.xml     | 74 ++++++++++++----------
 ...yCommandPublishingEntity_publishedCommands.java |  5 +-
 .../PropertyCommandPublishingPage-description.adoc | 28 +++++++-
 .../domainEvent/PropertyDomainEventPage.java       |  7 ++
 .../editing/PropertyEditingPage-description.adoc   | 66 ++++++++++++++-----
 ...ropertyExecutionPublishingPage-description.adoc |  6 +-
 .../jdo/EmbeddedTypePageJdo-description.adoc       |  4 +-
 26 files changed, 249 insertions(+), 127 deletions(-)

diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/_entities/DemoEntity.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/_entities/DemoEntity.java
deleted file mode 100644
index 145221becf..0000000000
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/_entities/DemoEntity.java
+++ /dev/null
@@ -1,26 +0,0 @@
-/*
- *  Licensed to the Apache Software Foundation (ASF) under one
- *  or more contributor license agreements.  See the NOTICE file
- *  distributed with this work for additional information
- *  regarding copyright ownership.  The ASF licenses this file
- *  to you under the Apache License, Version 2.0 (the
- *  "License"); you may not use this file except in compliance
- *  with the License.  You may obtain a copy of the License at
- *
- *        http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing,
- *  software distributed under the License is distributed on an
- *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- *  KIND, either express or implied.  See the License for the
- *  specific language governing permissions and limitations
- *  under the License.
- */
-package demoapp.dom.domain._entities;
-
-public abstract class DemoEntity {
-
-    public abstract String getProperty();
-    public abstract void setProperty(String value);
-
-}
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_changeNameNotPublished.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_changeNameNotPublished.java
index 04fdb9dfe8..098d99080a 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_changeNameNotPublished.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_changeNameNotPublished.java
@@ -20,6 +20,7 @@
 package demoapp.dom.domain.actions.Action.commandPublishing;
 
 import org.apache.causeway.applib.annotation.Action;
+import org.apache.causeway.applib.annotation.ActionLayout;
 import org.apache.causeway.applib.annotation.MemberSupport;
 import org.apache.causeway.applib.annotation.Publishing;
 
@@ -27,6 +28,9 @@ import lombok.RequiredArgsConstructor;
 
 //tag::class[]
 @Action(commandPublishing = Publishing.DISABLED)                    // <.>
+@ActionLayout(
+        describedAs = "This action does NOT have command publishing enabled"
+)
 @RequiredArgsConstructor
 public class ActionCommandPublishingEntity_changeNameNotPublished {
 
@@ -37,9 +41,12 @@ public class ActionCommandPublishingEntity_changeNameNotPublished {
         entity.setName(newName);
         return entity;
     }
+    // ...
+//end::class[]
 
     public String default0Act() {
         return entity.getName();
     }
+//tag::class[]
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_changeNamePublished.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_changeNamePublished.java
index 8762c11bfa..d732f91204 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_changeNamePublished.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_changeNamePublished.java
@@ -20,6 +20,7 @@
 package demoapp.dom.domain.actions.Action.commandPublishing;
 
 import org.apache.causeway.applib.annotation.Action;
+import org.apache.causeway.applib.annotation.ActionLayout;
 import org.apache.causeway.applib.annotation.MemberSupport;
 import org.apache.causeway.applib.annotation.Publishing;
 
@@ -27,6 +28,9 @@ import lombok.RequiredArgsConstructor;
 
 //tag::class[]
 @Action(commandPublishing = Publishing.ENABLED)                    // <.>
+@ActionLayout(
+    describedAs = "This action has command publishing enabled"
+)
 @RequiredArgsConstructor
 public class ActionCommandPublishingEntity_changeNamePublished {
 
@@ -37,9 +41,11 @@ public class ActionCommandPublishingEntity_changeNamePublished {
         entity.setName(newName);
         return entity;
     }
-
+    // ...
+//end::class[]
     public String default0Act() {
         return entity.getName();
     }
+//tag::class[]
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_publishedCommands.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_publishedCommands.java
index faade612f6..979e831d3f 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_publishedCommands.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingEntity_publishedCommands.java
@@ -21,10 +21,11 @@ public class ActionCommandPublishingEntity_publishedCommands {
     private final ActionCommandPublishingEntity entity;
 
     @MemberSupport public List<? extends CommandLogEntry> coll() {
-        return commandLogEntryRepository.findRecentByTarget(bookmarkService.bookmarkForElseFail(entity));
+        return commandLogEntryRepository.findRecentByTarget(
+                bookmarkService.bookmarkForElseFail(entity));
     }
 
-    @Inject CommandLogEntryRepository<? extends CommandLogEntry> commandLogEntryRepository;
+    @Inject CommandLogEntryRepository<? extends CommandLogEntry> commandLogEntryRepository; // <.>
     @Inject BookmarkService bookmarkService;
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage-description.adoc
index 2dbd7bfdb1..0ad3e68068 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage-description.adoc
@@ -17,7 +17,7 @@ The collection on the left hand side shows a list of entities, and two associate
 These actions can be used to change the name of any one of those entities.
 One of the actions is published, the other is not.
 
-Invoking the published action will result in a command representing the intention to invoke the action from being persisted.
+Invoking the published action will result in a command representing the intention to invoke the action being persisted.
 The link:https://causeway.apache.org/userguide/2.0.0-RC1/commandlog/about.html[commandlog] extension persists these as link:https://causeway.apache.org/refguide/2.0.0-RC1/extensions/index/commandlog/applib/dom/CommandLogEntry.html[CommandLogEntry] entities.
 These are listed in the second collection on the left.
 
@@ -59,6 +59,9 @@ causeway:
       action:
         command-publishing: "none"      # <.>
 ----
-<.> `none` | `disabled` | `enabled`.
+<.> can be one of:
+* `none` - by default, commands not published for any action
+* `ignore_safe` or `ignore_query_only` - commands published for all idempotent and non-idempotent actions, but not for query-only actions.
+* `all` - commands published for all actions (irrespective of their semantics)
 
 
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage_changeNameNotPublished.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage_changeNameNotPublished.java
index 0e34ee335b..c21b46becb 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage_changeNameNotPublished.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage_changeNameNotPublished.java
@@ -23,6 +23,7 @@ import java.util.List;
 import javax.inject.Inject;
 
 import org.apache.causeway.applib.annotation.Action;
+import org.apache.causeway.applib.annotation.ActionLayout;
 import org.apache.causeway.applib.annotation.MemberSupport;
 import org.apache.causeway.applib.annotation.Publishing;
 
@@ -30,6 +31,9 @@ import lombok.RequiredArgsConstructor;
 
 //tag::class[]
 @Action(commandPublishing = Publishing.DISABLED)                    // <.>
+@ActionLayout(
+    describedAs = "This action does NOT have command publishing enabled"
+)
 @RequiredArgsConstructor
 public class ActionCommandPublishingPage_changeNameNotPublished {
 
@@ -41,6 +45,8 @@ public class ActionCommandPublishingPage_changeNameNotPublished {
         entity.setName(newName);
         return page;
     }
+    // ...
+//end::class[]
 
     public List<? extends ActionCommandPublishingEntity> choices0Act() {
         return repository.all();
@@ -50,5 +56,6 @@ public class ActionCommandPublishingPage_changeNameNotPublished {
     }
 
     @Inject ActionCommandPublishingEntityRepository repository;
+//tag::class[]
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage_changeNamePublished.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage_changeNamePublished.java
index c1b328e3b4..b026f2ad75 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage_changeNamePublished.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/commandPublishing/ActionCommandPublishingPage_changeNamePublished.java
@@ -23,6 +23,7 @@ import java.util.List;
 import javax.inject.Inject;
 
 import org.apache.causeway.applib.annotation.Action;
+import org.apache.causeway.applib.annotation.ActionLayout;
 import org.apache.causeway.applib.annotation.MemberSupport;
 import org.apache.causeway.applib.annotation.Publishing;
 
@@ -30,6 +31,9 @@ import lombok.RequiredArgsConstructor;
 
 //tag::class[]
 @Action(commandPublishing = Publishing.ENABLED)                    // <.>
+@ActionLayout(
+    describedAs = "This action has command publishing enabled"
+)
 @RequiredArgsConstructor
 public class ActionCommandPublishingPage_changeNamePublished {
 
@@ -41,6 +45,8 @@ public class ActionCommandPublishingPage_changeNamePublished {
         entity.setName(newName);
         return page;
     }
+    // ...
+//end::class[]
 
     public List<? extends ActionCommandPublishingEntity> choices0Act() {
         return repository.all();
@@ -50,5 +56,6 @@ public class ActionCommandPublishingPage_changeNamePublished {
     }
 
     @Inject ActionCommandPublishingEntityRepository repository;
+//tag::class[]
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage_updateText.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage_updateText.java
index 119f510e14..85a8292d25 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage_updateText.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage_updateText.java
@@ -19,6 +19,7 @@
 package demoapp.dom.domain.actions.Action.domainEvent;
 
 import org.apache.causeway.applib.annotation.Action;
+import org.apache.causeway.applib.annotation.ActionLayout;
 import org.apache.causeway.applib.annotation.MemberSupport;
 import org.apache.causeway.applib.events.domain.ActionDomainEvent;
 
@@ -27,6 +28,9 @@ import lombok.RequiredArgsConstructor;
 
 //tag::class[]
 @Action(domainEvent = ActionDomainEventPage_updateText.DomainEvent.class)   // <.>
+@ActionLayout(
+    describedAs = "This action emits a custom domain event"
+)
 @RequiredArgsConstructor
 public class ActionDomainEventPage_updateText {
 
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage_updateTextNotAnnotated.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage_updateTextNotAnnotated.java
index 321ebd3934..512c009d69 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage_updateTextNotAnnotated.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/domainEvent/ActionDomainEventPage_updateTextNotAnnotated.java
@@ -19,6 +19,7 @@
 package demoapp.dom.domain.actions.Action.domainEvent;
 
 import org.apache.causeway.applib.annotation.Action;
+import org.apache.causeway.applib.annotation.ActionLayout;
 import org.apache.causeway.applib.annotation.MemberSupport;
 
 import lombok.RequiredArgsConstructor;
@@ -26,6 +27,9 @@ import lombok.RequiredArgsConstructor;
 
 //tag::class[]
 @Action()                                                       // <.>
+@ActionLayout(
+    describedAs = "This action emits only the default domain event"
+)
 @RequiredArgsConstructor
 public class ActionDomainEventPage_updateTextNotAnnotated {
     // ...
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingEntity_changeNameNotPublished.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingEntity_changeNameNotPublished.java
index bf75be8090..a50e5cd9a3 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingEntity_changeNameNotPublished.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingEntity_changeNameNotPublished.java
@@ -39,12 +39,12 @@ public class ActionExecutionPublishingEntity_changeNameNotPublished {
         entity.setName(newName);
         return entity;
     }
+    // ...
+//end::class[]
 
     public String default0Act() {
         return entity.getName();
     }
-
-    @Inject
-    ActionExecutionPublishingEntityRepository repository;
+//tag::class[]
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingEntity_changeNamePublished.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingEntity_changeNamePublished.java
index 266f769318..bd5edab4e9 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingEntity_changeNamePublished.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingEntity_changeNamePublished.java
@@ -39,12 +39,13 @@ public class ActionExecutionPublishingEntity_changeNamePublished {
         entity.setName(newName);
         return entity;
     }
+    // ...
+//end::class[]
 
     public String default0Act() {
         return entity.getName();
     }
 
-    @Inject
-    ActionExecutionPublishingEntityRepository repository;
+//tag::class[]
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage-description.adoc
index d770a0b28c..c4df3da76b 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage-description.adoc
@@ -5,10 +5,10 @@ Every action invocation is reified into an link:https://causeway.apache.org/refg
 
 The link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/annotation/Action.html#executionpublishing[@Action#executionPublishing] determines whether subscribers are notified of the action being executed.
 
-The _executionLog_ extension provides an out-of-the-box subscriber implementation that persists every published execution into a log.
+The link:https://causeway.apache.org/userguide/2.0.0-RC1/executionlog/about.html[executionlog] extension provides an out-of-the-box subscriber implementation that persists every published execution into a log.
 This can be invaluable for auditing and performance monitoring.
 
-The similar _executionOutbox_ extension (not part of this demo) is very similar, also persisting executions.
+The similar link:https://causeway.apache.org/userguide/2.0.0-RC1/executionoutbox/about.html[executionOutbox] extension (not part of this demo) is very similar, also persisting executions.
 It is designed for integration scenarios, interacting with downstream systems.
 
 It is of course also possible to register additional subscribers for your own purposes.
@@ -20,17 +20,16 @@ The collection on the left hand side shows a list of entities, and three associa
 These actions can be used to change the name of any one of those entities.
 
 * the `changeNamePublished` action has execution publishing enabled.
-+
 This will result in an execution representing the action invocation being persisted as an `ExecutionLogEntry`; these are listed in the collection at the bottom of the page.
 The execution of one of the actions is published, the other is not.
 
 * the `changeNameNotPublished` action has execution publishing disabled.
-+
 As you might expect, no `ExecutionLogEntry` is persisted for this.
 
-* the `changeNameWrapped` action also has execution publishing enabled, but is implemented by invoking a corresponding "changeName" action on the underlying entity, through the `WrapperFactory`
+* the `changeNameWrapped` action has execution publishing disabled, but it uses the link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/services/wrapper/WrapperFactory.html[WrapperFactory] to invoke the "changeNamePublished" action (above), which does.
+This results in an executions being published, with a corresponding link:https://causeway.apache.org/refguide/2.0.0-RC1/extensions/index/executionlog/applib/dom/ExecutionLogEntry.html[ExecutionLogEntry].
 +
-This results in executions for both the outer action and the delegate action both being published, with a corresponding `ExecutionLogEntry` for both.
+WARNING: no such execution log entry is currently created; tracking with link:https://issues.apache.org/jira/browse/CAUSEWAY-3476[CAUSEWAY-3476].
 
 You can also navigate into the entities and invoke actions on the objects themselves.
 These actions are also logged.
@@ -80,6 +79,10 @@ causeway:
       action:
         execution-publishing: "none"      # <.>
 ----
-<.> `none` | `disabled` | `enabled`.
+<.> can be one of:
+* `none` - by default, commands not published for any action
+* `ignore_safe` or `ignore_query_only` - commands published for all idempotent and non-idempotent actions, but not for query-only actions.
+* `all` - commands published for all actions (irrespective of their semantics)
+
 
 
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage.layout.xml b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage.layout.xml
index 103330f2ce..4ec6bff8a9 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage.layout.xml
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage.layout.xml
@@ -26,12 +26,21 @@
 
 	<bs3:row>
 		<bs3:col span="6">
-			<cpt:fieldSet name="Other" id="other" unreferencedProperties="true"/>
-			<cpt:collection id="objects">
-				<cpt:action id="changeNamePublished"/>
-				<cpt:action id="changeNameNotPublished"/>
-				<cpt:action id="changeNameWrapped"/>
-			</cpt:collection>
+            <bs3:row>
+                <bs3:col span="12">
+                    <cpt:fieldSet name="Other" id="other" unreferencedProperties="true"/>
+                    <cpt:collection id="objects">
+                        <cpt:action id="changeNamePublished"/>
+                        <cpt:action id="changeNameNotPublished"/>
+                        <cpt:action id="changeNameWrapped"/>
+                    </cpt:collection>
+                </bs3:col>
+            </bs3:row>
+            <bs3:row>
+                <bs3:col span="12">
+                    <cpt:collection id="publishedExecutions"/>
+                </bs3:col>
+            </bs3:row>
 		</bs3:col>
 		<bs3:col span="6">
 			<cpt:fieldSet name="Description" id="description" >
@@ -50,11 +59,6 @@
 			</cpt:fieldSet>
 		</bs3:col>
 	</bs3:row>
-	<bs3:row>
-		<bs3:col span="12">
-			<cpt:collection id="publishedExecutions"/>
-		</bs3:col>
-	</bs3:row>
 	<bs3:row>
 		<bs3:col span="12" unreferencedCollections="true"/>
 	</bs3:row>
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNameNotPublished.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNameNotPublished.java
index 8a39161bc7..7ab5c10e22 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNameNotPublished.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNameNotPublished.java
@@ -23,6 +23,7 @@ import java.util.List;
 import javax.inject.Inject;
 
 import org.apache.causeway.applib.annotation.Action;
+import org.apache.causeway.applib.annotation.ActionLayout;
 import org.apache.causeway.applib.annotation.MemberSupport;
 import org.apache.causeway.applib.annotation.Publishing;
 
@@ -30,6 +31,9 @@ import lombok.RequiredArgsConstructor;
 
 //tag::class[]
 @Action(executionPublishing = Publishing.DISABLED)                    // <.>
+@ActionLayout(
+    describedAs = "This action does NOT have execution publishing enabled"
+)
 @RequiredArgsConstructor
 public class ActionExecutionPublishingPage_changeNameNotPublished {
 
@@ -41,6 +45,8 @@ public class ActionExecutionPublishingPage_changeNameNotPublished {
         entity.setName(newName);
         return page;
     }
+    // ...
+//end::class[]
 
     public List<? extends ActionExecutionPublishingEntity> choices0Act() {
         return repository.all();
@@ -50,5 +56,6 @@ public class ActionExecutionPublishingPage_changeNameNotPublished {
     }
 
     @Inject ActionExecutionPublishingEntityRepository repository;
+//tag::class[]
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNamePublished.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNamePublished.java
index a0625b5be4..ebbe8ca74f 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNamePublished.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNamePublished.java
@@ -23,6 +23,7 @@ import java.util.List;
 import javax.inject.Inject;
 
 import org.apache.causeway.applib.annotation.Action;
+import org.apache.causeway.applib.annotation.ActionLayout;
 import org.apache.causeway.applib.annotation.MemberSupport;
 import org.apache.causeway.applib.annotation.Publishing;
 
@@ -30,6 +31,9 @@ import lombok.RequiredArgsConstructor;
 
 //tag::class[]
 @Action(executionPublishing = Publishing.ENABLED)                    // <.>
+@ActionLayout(
+    describedAs = "This action has execution publishing enabled"
+)
 @RequiredArgsConstructor
 public class ActionExecutionPublishingPage_changeNamePublished {
 
@@ -41,6 +45,8 @@ public class ActionExecutionPublishingPage_changeNamePublished {
         entity.setName(newName);
         return page;
     }
+    // ...
+//end::class[]
 
     public List<? extends ActionExecutionPublishingEntity> choices0Act() {
         return repository.all();
@@ -50,5 +56,6 @@ public class ActionExecutionPublishingPage_changeNamePublished {
     }
 
     @Inject ActionExecutionPublishingEntityRepository repository;
+//tag::class[]
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNameWrapped.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNameWrapped.java
index 20b7ab77e0..4fdfa78ed1 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNameWrapped.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/executionPublishing/ActionExecutionPublishingPage_changeNameWrapped.java
@@ -23,6 +23,7 @@ import java.util.List;
 import javax.inject.Inject;
 
 import org.apache.causeway.applib.annotation.Action;
+import org.apache.causeway.applib.annotation.ActionLayout;
 import org.apache.causeway.applib.annotation.MemberSupport;
 import org.apache.causeway.applib.annotation.Publishing;
 import org.apache.causeway.applib.services.wrapper.WrapperFactory;
@@ -30,7 +31,10 @@ import org.apache.causeway.applib.services.wrapper.WrapperFactory;
 import lombok.RequiredArgsConstructor;
 
 //tag::class[]
-@Action(executionPublishing = Publishing.ENABLED)                                                             // <.>
+@Action(executionPublishing = Publishing.DISABLED)                                              // <.>
+@ActionLayout(
+    describedAs = "This action does NOT have execution publishing enabled, but wraps an action that does"
+)
 @RequiredArgsConstructor
 public class ActionExecutionPublishingPage_changeNameWrapped {
 
@@ -39,9 +43,12 @@ public class ActionExecutionPublishingPage_changeNameWrapped {
     @MemberSupport public ActionExecutionPublishingPage act(
             final ActionExecutionPublishingEntity entity,
             final String newName) {
-        wrapperFactory.wrapMixin(ActionExecutionPublishingEntity_changeNamePublished.class, entity).act(newName); // <.>
+        wrapperFactory.wrapMixin(                                                               // <.>
+                ActionExecutionPublishingEntity_changeNamePublished.class, entity).act(newName);
         return page;
     }
+    // ...
+//end::class[]
 
     public List<? extends ActionExecutionPublishingEntity> choices0Act() {
         return repository.all();
@@ -51,6 +58,7 @@ public class ActionExecutionPublishingPage_changeNameWrapped {
     }
 
     @Inject ActionExecutionPublishingEntityRepository repository;
+//tag::class[]
     @Inject WrapperFactory wrapperFactory;
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/semantics/ActionSemanticsPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/semantics/ActionSemanticsPage-description.adoc
index 1d8dc8b958..a9b9daa2dc 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/semantics/ActionSemanticsPage-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/semantics/ActionSemanticsPage-description.adoc
@@ -2,7 +2,7 @@
 
 The link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/annotation/Action.html#semantics[@Action#semantics] attribute specifies whether invoking the action will change the state of the system, and if so, how:
 
-* `SAFE` (sometimes also called "query-only") means no side-effects, that is, no permanent change in state of the system
+* `SAFE` (also called "query-only") means no side-effects, that is, no permanent change in state of the system
 
 * `IDEMPOTENT` means that the state of the system will change, but invoking the action again (with the same arguments) will not change the state; in other words re-runnable
 
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage-description.adoc
index ad62ac6a61..a970cdc72b 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/actions/Action/typeOf/ActionTypeOfPage-description.adoc
@@ -9,16 +9,21 @@ In these cases the link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/in
 
 == How this demo works
 
-This page object defines a `children` collection:
+On the left hand side is a collection of entities that each have several properties.
+There are also three actions that can be used to find a subset of these entities; they all return a standalone collection.
+The three actions vary in how (or whether) they specify the element type of the returned collection.
 
+In terms of code:
+
+* the page object defines the `cihldren` collection:
++
 [source,java]
 ----
 include::ActionTypeOfPage.java[tags=class-collections-children]
 ----
 
-It also defines three variants of a "find" action, which all do the same thing: return those objects whose name matches.
-
-* the `find` action uses a generic parameter list:
+* the `find` action uses a generic parameter list.
+This is the preferred approach:
 +
 [source,java,indent=0]
 ----
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity.java
index 0d5ba2c24a..d3408403cf 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity.java
@@ -48,8 +48,11 @@ public abstract class PropertyCommandPublishingEntity
 
 //tag::published[]
     @Property(
-            editing = Editing.ENABLED,                  // <.>
-            commandPublishing = Publishing.ENABLED      // <.>
+        editing = Editing.ENABLED,                  // <.>
+        commandPublishing = Publishing.ENABLED      // <.>
+    )
+    @PropertyLayout(
+        describedAs = "This property has command publishing enabled"
     )
     public abstract String getName();
     public abstract void setName(String value);
@@ -57,10 +60,13 @@ public abstract class PropertyCommandPublishingEntity
 
 //tag::not-published[]
     @Property(
-            editing = Editing.ENABLED,                  // <.>
-            commandPublishing = Publishing.DISABLED     // <.>
+        editing = Editing.ENABLED,                  // <.>
+        commandPublishing = Publishing.DISABLED     // <.>
+    )
+    @PropertyLayout(
+        describedAs = "This property does NOT have command publishing enabled",
+        multiLine = 5
     )
-    @PropertyLayout(multiLine = 5)
     public abstract String getNotes();
     public abstract void setNotes(String value);
 //end::not-published[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity.layout.xml b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity.layout.xml
index 77d0156500..064acc5824 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity.layout.xml
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity.layout.xml
@@ -26,36 +26,45 @@
 
 	<bs3:row>
 		<bs3:col span="6">
-			<bs3:tabGroup>
-				<bs3:tab name="General">
-					<bs3:row>
-						<bs3:col span="12">
-							<cpt:fieldSet name="General" id="general" >
-								<cpt:property id="name"/>
-								<cpt:property id="notes"/>
-							</cpt:fieldSet>
-						</bs3:col>
-					</bs3:row>
-				</bs3:tab>
-				<bs3:tab name="Metadata">
-					<bs3:row>
-						<bs3:col span="12">
-							<cpt:fieldSet name="Metadata" id="metadata" >
-								<cpt:property id="id"/>
-								<cpt:property id="logicalTypeName"/>
-								<cpt:property id="version"/>
-							</cpt:fieldSet>
-						</bs3:col>
-					</bs3:row>
-				</bs3:tab>
-				<bs3:tab name="Other">
-					<bs3:row>
-						<bs3:col span="12">
-							<cpt:fieldSet name="Other" id="other" unreferencedProperties="true"/>
-						</bs3:col>
-					</bs3:row>
-				</bs3:tab>
-			</bs3:tabGroup>
+            <bs3:row>
+                <bs3:col span="12">
+                    <bs3:tabGroup>
+                        <bs3:tab name="General">
+                            <bs3:row>
+                                <bs3:col span="12">
+                                    <cpt:fieldSet name="General" id="general" >
+                                        <cpt:property id="name"/>
+                                        <cpt:property id="notes"/>
+                                    </cpt:fieldSet>
+                                </bs3:col>
+                            </bs3:row>
+                        </bs3:tab>
+                        <bs3:tab name="Metadata">
+                            <bs3:row>
+                                <bs3:col span="12">
+                                    <cpt:fieldSet name="Metadata" id="metadata" >
+                                        <cpt:property id="id"/>
+                                        <cpt:property id="logicalTypeName"/>
+                                        <cpt:property id="version"/>
+                                    </cpt:fieldSet>
+                                </bs3:col>
+                            </bs3:row>
+                        </bs3:tab>
+                        <bs3:tab name="Other">
+                            <bs3:row>
+                                <bs3:col span="12">
+                                    <cpt:fieldSet name="Other" id="other" unreferencedProperties="true"/>
+                                </bs3:col>
+                            </bs3:row>
+                        </bs3:tab>
+                    </bs3:tabGroup>
+                </bs3:col>
+            </bs3:row>
+            <bs3:row>
+                <bs3:col span="12">
+                    <cpt:collection id="publishedCommands"/>
+                </bs3:col>
+            </bs3:row>
 		</bs3:col>
 		<bs3:col span="6">
 			<cpt:fieldSet name="Description" id="description" >
@@ -74,11 +83,6 @@
 			</cpt:fieldSet>
 		</bs3:col>
 	</bs3:row>
-	<bs3:row>
-		<bs3:col span="12">
-			<cpt:collection id="publishedCommands"/>
-		</bs3:col>
-	</bs3:row>
 	<bs3:row>
 		<bs3:col span="12" unreferencedCollections="true"/>
 	</bs3:row>
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity_publishedCommands.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity_publishedCommands.java
index 80472ac2c9..51d233c2c8 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity_publishedCommands.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingEntity_publishedCommands.java
@@ -21,10 +21,11 @@ public class PropertyCommandPublishingEntity_publishedCommands {
     private final PropertyCommandPublishingEntity entity;
 
     @MemberSupport public List<? extends CommandLogEntry> coll() {
-        return commandLogEntryRepository.findRecentByTarget(bookmarkService.bookmarkForElseFail(entity));
+        return commandLogEntryRepository.findRecentByTarget(
+                bookmarkService.bookmarkForElseFail(entity));
     }
 
-    @Inject CommandLogEntryRepository<? extends CommandLogEntry> commandLogEntryRepository;
+    @Inject CommandLogEntryRepository<? extends CommandLogEntry> commandLogEntryRepository; // <.>
     @Inject BookmarkService bookmarkService;
 }
 //end::class[]
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingPage-description.adoc
index a718bbd264..3dae704594 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingPage-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/commandPublishing/PropertyCommandPublishingPage-description.adoc
@@ -17,9 +17,31 @@ The collection on the left hand side shows a list of entities.
 Those entities have two properties, `name` and `description`.
 Both of these properties may be edited, but only the `name` property has command publishing enabled.
 
-Navigate into the entities and edit the properties.
+Editing the published property will result in a command representing the intention to edit the property being persisted.
+The link:https://causeway.apache.org/userguide/2.0.0-RC1/commandlog/about.html[commandlog] extension persists these as link:https://causeway.apache.org/refguide/2.0.0-RC1/extensions/index/commandlog/applib/dom/CommandLogEntry.html[CommandLogEntry] entities.
 
-Invoking the published property will result in a command representing the property edit invocation from being persisted; these are listed in the collection at the bottom of the entity.
+To see this happening you will need to navigate into the entities and edit properties on the objects themselves.
+
+In terms of code:
+
+* property with command publishing enabled:
++
+[source,java,indent=0]
+..PropertyCommandPublishingEntity.java
+----
+include::PropertyCommandPublishingEntity.java[tags=published]
+----
+<.> makes the property editable...
+<.> \... and enables command publishing
+
+* contributed collection showing persisted ``CommandLogEntry``s:
++
+[source,java,indent=0]
+.PropertyCommandPublishingEntity_publishedCommands.java
+----
+include::PropertyCommandPublishingEntity_publishedCommands.java[tags=class]
+----
+<.> repository provided by the _commandLog_ extension.
 
 
 == Related configuration property
@@ -35,6 +57,6 @@ causeway:
       property:
         command-publishing: "none"      # <.>
 ----
-<.> `none` | `disabled` | `enabled`.
+<.> either `none` or `all`
 
 
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/domainEvent/PropertyDomainEventPage.java b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/domainEvent/PropertyDomainEventPage.java
index f34e325730..7cc87a1547 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/domainEvent/PropertyDomainEventPage.java
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/domainEvent/PropertyDomainEventPage.java
@@ -30,6 +30,7 @@ import org.apache.causeway.applib.annotation.Editing;
 import org.apache.causeway.applib.annotation.Nature;
 import org.apache.causeway.applib.annotation.ObjectSupport;
 import org.apache.causeway.applib.annotation.Property;
+import org.apache.causeway.applib.annotation.PropertyLayout;
 import org.apache.causeway.applib.events.domain.PropertyDomainEvent;
 
 import lombok.Getter;
@@ -66,11 +67,17 @@ public class PropertyDomainEventPage implements HasAsciiDocDescription {
         extends PropertyDomainEvent<PropertyDomainEventPage,String> {}
 
     @Property(domainEvent = TextDomainEvent.class)                  // <.>
+    @PropertyLayout(
+        describedAs = "This property emits a custom domain event"
+    )
     @XmlElement(required = true)
     @Getter @Setter
     private String text;
 
     @Property()                                                     // <.>
+    @PropertyLayout(
+        describedAs = "This property emits only the default domain event"
+    )
     @XmlElement(required = true)
     @Getter @Setter
     private String otherText;
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/editing/PropertyEditingPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/editing/PropertyEditingPage-description.adoc
index 8f70f26f26..5ed90387b3 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/editing/PropertyEditingPage-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/editing/PropertyEditingPage-description.adoc
@@ -2,26 +2,15 @@
 
 The state of the application can be changed either by invoking actions on domain objects, or by directly editing their properties.
 
-If the application has complicated business logic, then it's usually preferable to make all changes using actions, with editing globally disabled using a configuration property:
-
-[source,yaml]
-.application.yml
-----
-causeway:
-  applib:
-    annotation:
-      domain-object:
-        editing: false    # false | true
-----
-
+If the application has complicated business logic, then it's usually preferable to make all changes using actions, with editing globally disabled using a configuration property (see section below).
 This demo application is configured in this recommended way, with property editing disabled by default.
 
-The link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/annotation/Property.html#editing[@Property#editing] annotation allows this to be overridden for a specific property.
+However, the link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/annotation/Property.html#editing[@Property#editing] annotation allows this to be overridden for a specific property.
 
-Note that it's also possible to override the default for a specific object, so that all of its properties using link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/annotation/DomainObject.html#editing[@DomainObject#editing].
+It's also possible to override the default for a specific object, so that all of its properties using link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/annotation/DomainObject.html#editing[@DomainObject#editing].
 There are therefore three levels at which property editing can be defined:
 
-    @Property > @DomainObject > global configuration property
+    global configuration property < @DomainObject < @Property
 
 Alternatively, this works in the opposite direction also: if the global config property is to _allow_ properties to be edited, then the `@DomainObject#editing` (or `@Property#editing`) could be used to disable editing.
 This would be much less common, though.
@@ -35,5 +24,50 @@ In addition, the link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/inde
 The collection on the left shows a set of entity instances, which use `@Property#editing` to enable editing of one of their properties.
 The "initialCharacter" property cannot be edited either, because it is a derived property (has only a getter).
 
-Navigate through to the entity in order to edit its properties, and to see the corresponding source code.
+You'll need to navigate through to the entity in order to edit its properties.
+
+In terms of code:
+
+* for the `name` property, editing has been explicitly enabled:
++
+[source,java,indent=0]
+.PropertyEditingEntityImpl.java
+----
+include::jpa/PropertyEditingEntityImpl.java[tags=name]
+----
+<.> editing is enabled after all
+
+* The `originalName` property remains as not editable.
++
+It uses `@Property#editingDisabledReason` to explain why:
++
+[source,java,indent=0]
+.PropertyEditingEntityImpl.java
+----
+include::jpa/PropertyEditingEntityImpl.java[tags=original-name]
+----
+<.> this reason is rendered in the UI as a tooltip
+
+* Meanwhile the `initialCharacter` property is also not editable (this time, because it is derived) but has no additional annotations:
++
+[source,java,indent=0]
+.PropertyEditingEntityImpl.java
+----
+include::jpa/PropertyEditingEntityImpl.java[tags=initial-character]
+----
+
+
+
+== Configuration Property
+
+If the application has complicated business logic, then it's usually preferable to make all changes using actions, with editing globally disabled using a configuration property:
 
+[source,yaml]
+.application.yml
+----
+causeway:
+  applib:
+    annotation:
+      domain-object:
+        editing: false    # false | true
+----
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/executionPublishing/PropertyExecutionPublishingPage-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/executionPublishing/PropertyExecutionPublishingPage-description.adoc
index e6fd7aa4e6..e8a35b968b 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/executionPublishing/PropertyExecutionPublishingPage-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/domain/properties/Property/executionPublishing/PropertyExecutionPublishingPage-description.adoc
@@ -5,10 +5,10 @@ Every property edit is reified into an link:https://causeway.apache.org/refguide
 
 The link:https://causeway.apache.org/refguide/2.0.0-RC1/applib/index/annotation/Property.html#executionpublishing[@Property#executionPublishing] determines whether subscribers are notified of the property being edited.
 
-The _executionLog_ extension provides an out-of-the-box subscriber implementation that persists every published execution into a log.
+The link:https://causeway.apache.org/userguide/2.0.0-RC1/executionlog/about.html[executionlog] extension provides an out-of-the-box subscriber implementation that persists every published execution into a log.
 This can be invaluable for auditing and performance monitoring.
 
-The similar _executionOutbox_ extension (not part of this demo) is very similar, also persisting executions.
+The similar link:https://causeway.apache.org/userguide/2.0.0-RC1/executionoutbox/about.html[executionOutbox] extension (not part of this demo) is very similar, also persisting executions.
 It is designed for integration scenarios, interacting with downstream systems.
 
 It is of course also possible to register additional subscribers for your own purposes.
@@ -38,6 +38,6 @@ causeway:
       property:
         execution-publishing: "none"      # <.>
 ----
-<.> `none` | `disabled` | `enabled`.
+<.> either `none` or `all`
 
 
diff --git a/examples/demo/domain/src/main/java/demoapp/dom/progmodel/customvaluetypes/embeddedvalues/jdo/EmbeddedTypePageJdo-description.adoc b/examples/demo/domain/src/main/java/demoapp/dom/progmodel/customvaluetypes/embeddedvalues/jdo/EmbeddedTypePageJdo-description.adoc
index 5c51b7262a..57da250d10 100644
--- a/examples/demo/domain/src/main/java/demoapp/dom/progmodel/customvaluetypes/embeddedvalues/jdo/EmbeddedTypePageJdo-description.adoc
+++ b/examples/demo/domain/src/main/java/demoapp/dom/progmodel/customvaluetypes/embeddedvalues/jdo/EmbeddedTypePageJdo-description.adoc
@@ -7,7 +7,7 @@ Such embedded types have no identity in and of themselves; they are identified o
 Embedded types themselves can be mutable or immutable.
 When immutable, they are very similar to value types.
 However, they are not quite true value types as the ORM needs to update their fields directly.
-To enable that, a mutator method is required, though it can be made `private`
+To enable that, a mutator method is required, though it can be made `private`.
 
 
 == How this demo works
@@ -34,7 +34,7 @@ include::NumberConstantJdo.java[tags=class]
 ----
 include::ComplexNumberJdo.java[tags=class]
 ----
-<.> JDO `@EmbeddedOnly` annotation is the companion of `@Embedded` on the owning object
+<.> JDO `@EmbeddedOnly` annotation is the companion of `@Embedded` on the owning object.
 <.> with presence of `@EmbeddedOnly` should not be required; but app fails on launch if not provided.
 <.> Indicates to the framework that this is a value rather than an entity.
 Accordingly, we will also need to provide a `ValueSemanticsProvider` implementation, discussed below.