You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@isis.apache.org by da...@apache.org on 2020/03/03 07:09:30 UTC

[isis] 02/02: ISIS-2062: sync examples, adds in tags for refguide

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

danhaywood pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/isis.git

commit df9e8bc0b847fb3e485fefaf8bd083c2286ecdbc
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Mar 3 07:08:18 2020 +0000

    ISIS-2062: sync examples, adds in tags for refguide
---
 .../examples/services/audit/AuditerService.java    |  12 +-
 .../services/audit/AuditerServiceLogging.java      |  10 +-
 .../examples/services/bookmark/Bookmark.java       |  22 ++--
 .../services/bookmark/BookmarkHolder_lookup.java   |   6 +-
 .../services/bookmark/BookmarkHolder_object.java   |   7 +-
 .../services/bookmark/BookmarkService.java         |  56 +++++++--
 .../services/bookmarkui/BookmarkUiService.java     |   2 +-
 .../examples/services/command/Command.java         |  13 +-
 .../examples/services/command/CommandContext.java  |  13 +-
 .../services/command/CommandExecutorService.java   |  15 ++-
 .../services/command/spi/CommandService.java       |  12 +-
 .../services/confview/ConfigurationMenu.java       |   8 +-
 .../confview/ConfigurationViewService.java         |   2 +
 .../services/conmap/ContentMappingService.java     |   8 +-
 .../examples/services/email/EmailService.java      |   8 +-
 .../applib-svc/examples/services/error/Ticket.java |  12 ++
 .../services/exceprecog/ExceptionRecognizer.java   |  62 +++++++---
 .../exceprecog/ExceptionRecognizerService.java     |  27 +++--
 .../services/exceprecog/TranslatableException.java |   4 +
 .../examples/services/factory/FactoryService.java  |  52 +++++---
 .../examples/services/grid/GridLoaderService.java  |  10 ++
 .../examples/services/grid/GridService.java        |  18 +++
 .../examples/services/grid/GridSystemService.java  |   4 +
 .../examples/services/health/Health.java           |   2 +
 .../examples/services/hint/HintStore.java          |   8 +-
 .../services/homepage/HomePageResolverService.java |   1 +
 .../examples/services/homepage/package-info.java}  |  13 +-
 .../examples/services/i18n/TranslatableString.java |  26 +++-
 .../examples/services/i18n/TranslationService.java |  57 +++++++--
 .../examples/services/iactn/Interaction.java       | 131 ++++++++++++++++-----
 .../services/iactn/InteractionContext.java         |   9 +-
 .../examples/services/inject/ServiceInjector.java  |   5 +
 .../examples/services/jaxb/JaxbService.java        |  14 ++-
 .../examples/services/layout/LayoutService.java    |  24 +++-
 .../examples/services/linking/DeepLinkService.java |   2 +
 .../services/menu/MenuBarsLoaderService.java       |   4 +
 .../examples/services/menu/MenuBarsService.java    |  13 +-
 .../examples/services/message/MessageService.java  |  18 +++
 .../examples/services/metamodel/DomainMember.java  |  12 +-
 .../examples/services/metamodel/DomainModel.java   |   2 +
 .../services/metamodel/MetaModelService.java       |  27 +++--
 .../isis/applib/services/audit/AuditerService.java |  12 +-
 .../services/audit/AuditerServiceLogging.java      |  10 +-
 .../isis/applib/services/bookmark/Bookmark.java    |  22 ++--
 .../services/bookmark/BookmarkHolder_lookup.java   |   6 +-
 .../services/bookmark/BookmarkHolder_object.java   |   7 +-
 .../applib/services/bookmark/BookmarkService.java  |  54 +++++++--
 .../services/bookmarkui/BookmarkUiService.java     |   2 +-
 .../isis/applib/services/command/Command.java      |  11 +-
 .../applib/services/command/CommandContext.java    |   5 +-
 .../services/command/CommandExecutorService.java   |  15 ++-
 .../services/command/spi/CommandService.java       |  12 +-
 .../confview/ConfigurationViewService.java         |   2 +
 .../services/conmap/ContentMappingService.java     |   8 +-
 .../isis/applib/services/email/EmailService.java   |   8 +-
 .../apache/isis/applib/services/error/Ticket.java  |  12 ++
 .../services/exceprecog/ExceptionRecognizer.java   |  62 +++++++---
 .../exceprecog/ExceptionRecognizerService.java     |  27 +++--
 .../services/exceprecog/TranslatableException.java |   4 +
 .../applib/services/factory/FactoryService.java    |  52 +++++---
 .../applib/services/grid/GridLoaderService.java    |  10 ++
 .../isis/applib/services/grid/GridService.java     |  18 +++
 .../applib/services/grid/GridSystemService.java    |   4 +
 .../apache/isis/applib/services/health/Health.java |   2 +
 .../isis/applib/services/hint/HintStore.java       |   8 +-
 .../services/homepage/HomePageResolverService.java |   1 +
 .../package-info.java}                             |  13 +-
 .../applib/services/i18n/TranslatableString.java   |  26 +++-
 .../applib/services/i18n/TranslationService.java   |  57 +++++++--
 .../isis/applib/services/iactn/Interaction.java    | 131 ++++++++++++++++-----
 .../applib/services/iactn/InteractionContext.java  |   9 +-
 .../applib/services/inject/ServiceInjector.java    |   5 +
 .../isis/applib/services/jaxb/JaxbService.java     |  14 ++-
 .../isis/applib/services/layout/LayoutService.java |  24 +++-
 .../applib/services/linking/DeepLinkService.java   |   2 +
 .../services/menu/MenuBarsLoaderService.java       |   4 +
 .../isis/applib/services/menu/MenuBarsService.java |  13 +-
 .../applib/services/message/MessageService.java    |  18 +++
 .../applib/services/metamodel/DomainMember.java    |  12 +-
 .../applib/services/metamodel/DomainModel.java     |   2 +
 .../services/metamodel/MetaModelService.java       |  27 +++--
 .../bookmarks/BookmarkServiceDefault.java          |   4 +-
 82 files changed, 1069 insertions(+), 417 deletions(-)

diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerService.java
index 12bcc47..5cfc02a 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerService.java
@@ -42,16 +42,16 @@ import org.apache.isis.applib.services.bookmark.Bookmark;
 // tag::refguide[]
 public interface AuditerService {
 
-    boolean isEnabled();                                            // <1>
+    boolean isEnabled();                                            // <.>
 
     void audit(
-            final UUID interactionId, final int sequence,           // <2>
+            final UUID interactionId, final int sequence,           // <.>
             final String targetClassName,
-            final Bookmark target,                                  // <3>
+            final Bookmark target,                                  // <.>
             final String memberIdentifier,
-            final String propertyName,                              // <4>
-            final String preValue, final String postValue,          // <5>
-            final String user, final Timestamp timestamp);          // <6>
+            final String propertyName,                              // <.>
+            final String preValue, final String postValue,          // <.>
+            final String user, final Timestamp timestamp);          // <.>
 
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerServiceLogging.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerServiceLogging.java
index adc9570..ebd7a23 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerServiceLogging.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/audit/AuditerServiceLogging.java
@@ -59,10 +59,12 @@ public class AuditerServiceLogging implements AuditerService {
             final String preValue, final String postValue,
             final String user, final Timestamp timestamp) {
 
-        String auditMessage =
-                interactionId + "," + sequence + ": " +
-                        target.toString() + " by " + user + ", " + propertyName + ": " + preValue + " -> " + postValue;
-        log.debug(auditMessage);
+        if(log.isDebugEnabled()) {
+            String auditMessage =
+                    interactionId + "," + sequence + ": " +
+                            target.toString() + " by " + user + ", " + propertyName + ": " + preValue + " -> " + postValue;
+            log.debug(auditMessage);
+        }
     }
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java
index 481db35..dc0e771 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/Bookmark.java
@@ -43,7 +43,7 @@ import lombok.val;
 // tag::refguide[]
 public class Bookmark implements Serializable {
 
-// end::refguide[]
+    // end::refguide[]
     private static final long serialVersionUID = 2L;
 
     protected static final String SEPARATOR = ":";
@@ -52,26 +52,28 @@ public class Bookmark implements Serializable {
      * corresponds directly to the object's specification-id
      * @see <code>RootOid</code>
      */
-// tag::refguide[]
+    // tag::refguide[]
     @NonNull  private final String objectType;
     @NonNull  private final String identifier;
-// end::refguide[]
+    // end::refguide[]
+
     @Nullable private final String hintId;
-// tag::refguide[]
+    // tag::refguide[]
 
     public static Bookmark of(String objectType, String identifier) {
         return new Bookmark(objectType, identifier, /*hintId*/ null);
     }
     // ...
 
-// end::refguide[]
+    // end::refguide[]
 
     /**
      * Round-trip with {@link #toString()} representation.
      */
-// tag::refguide[]
+    // tag::refguide[]
     public static Optional<Bookmark> parse(@Nullable String str) {
-// end::refguide[]
+    // end::refguide[]
+
         if(str==null) {
             return Optional.empty();
         }
@@ -85,10 +87,10 @@ public class Bookmark implements Serializable {
         }
         return Optional.empty();
 
-// tag::refguide[]
+        // tag::refguide[]
         // ...
     }
-// end::refguide[]
+    // end::refguide[]
 
     public OidDto toOidDto() {
         val oidDto = new OidDto();
@@ -122,6 +124,6 @@ public class Bookmark implements Serializable {
         return objectType + SEPARATOR + id;
     }
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_lookup.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_lookup.java
index de4cfca..846273b 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_lookup.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_lookup.java
@@ -27,7 +27,6 @@ import org.apache.isis.applib.annotation.Contributed;
 import org.apache.isis.applib.annotation.Mixin;
 import org.apache.isis.applib.annotation.SemanticsOf;
 
-// tag::refguide[]
 @Mixin(method = "act")
 public class BookmarkHolder_lookup {
 
@@ -42,11 +41,11 @@ public class BookmarkHolder_lookup {
     @Action(
             domainEvent = ActionDomainEvent.class,
             semantics = SemanticsOf.SAFE
-            )
+    )
     @ActionLayout(
             contributed = Contributed.AS_ACTION,
             cssClassFa = "fa-bookmark"
-            )
+    )
     public Object act() {
         return bookmarkService.lookup(bookmarkHolder);
     }
@@ -54,4 +53,3 @@ public class BookmarkHolder_lookup {
     @Inject private BookmarkService bookmarkService;
 
 }
-// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_object.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_object.java
index 2565c2b..86b8528 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_object.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkHolder_object.java
@@ -27,7 +27,6 @@ import org.apache.isis.applib.annotation.Contributed;
 import org.apache.isis.applib.annotation.Mixin;
 import org.apache.isis.applib.annotation.SemanticsOf;
 
-// tag::refguide[]
 @Mixin(method = "prop")
 public class BookmarkHolder_object {
 
@@ -42,16 +41,14 @@ public class BookmarkHolder_object {
     @Action(
             semantics = SemanticsOf.SAFE,
             domainEvent = BookmarkHolder_object.ActionDomainEvent.class
-            )
+    )
     @ActionLayout(
             contributed = Contributed.AS_ASSOCIATION
-            )
+    )
     public Object prop() {
         return bookmarkService.lookup(bookmarkHolder);
     }
 
-
     @Inject private BookmarkService bookmarkService;
 
 }
-// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java
index 1751729..a0ef829 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmark/BookmarkService.java
@@ -20,6 +20,7 @@ package org.apache.isis.applib.services.bookmark;
 
 import javax.annotation.Nullable;
 
+import org.apache.isis.applib.services.metamodel.MetaModelService;
 import org.apache.isis.core.commons.internal.base._Casts;
 import org.apache.isis.core.commons.internal.exceptions._Exceptions;
 
@@ -34,43 +35,76 @@ import lombok.val;
 // tag::refguide[]
 public interface BookmarkService {
 
-// end::refguide[]
+    // end::refguide[]
     /**
-     * Given any {@link Bookmark} this service is able to reconstruct to originating domain object the {@link Bookmark}
-     * was created for.
+     * Returns the {@link Bookmark} for the given domain object.
+     *
      * <p>
-     * Note: Not every domain object is bookmark-able.
+     * <b>Note</b>: Not every domain object is bookmark-able: only entities, view models and services (NOT values or collections)
      * </p>
-     * @param domainObject
+     *
+     * @param domainObject - domain object (if any) to return a bookmark for
      * @return optionally a {@link Bookmark} representing given {@code domainObject}
      */
-// tag::refguide[]
+    // tag::refguide[]
     Bookmark bookmarkFor(@Nullable Object domainObject);
 
+    // end::refguide[]
+    /**
+     * As per {@link #bookmarkFor(Object)}, but requires that a non-null {@link Bookmark} is returned.
+     *
+     * @param domainObject - that can be bookmarked
+     * @return a (non-null) {@link Bookmark} for the provided domain object.
+     */
+    // tag::refguide[]
     default Bookmark bookmarkForElseThrow(Object domainObject) {
-// end::refguide[]
+        // end::refguide[]
+
         requires(domainObject, "domainObject");
         val bookmark = bookmarkFor(domainObject);
         if(bookmark!=null) {
             return bookmark;
         }
         throw _Exceptions.illegalArgument(
-                        "cannot create bookmark for type %s", domainObject.getClass().getName());
-// tag::refguide[]
+                "cannot create bookmark for type %s", domainObject.getClass().getName());
+        // tag::refguide[]
         // ...
     }
 
+    // end::refguide[]
+    /**
+     * Utility method that creates a {@link Bookmark} from the constituent parts.
+     *
+     * @return - {@link Bookmark} for provided class and identifier
+     */
+    // tag::refguide[]
     Bookmark bookmarkFor(Class<?> cls, String identifier);
 
+    // end::refguide[]
+    /**
+     * @see #lookup(Bookmark)
+     *
+     * @param bookmarkHolder - from which the {@link Bookmark} is obtained
+     * @return - corresponding domain object
+     */
+    // tag::refguide[]
     Object lookup(BookmarkHolder bookmarkHolder);
 
+    // end::refguide[]
+    /**
+     * Reciprocal of {@link #bookmarkFor(Object)}
+     *
+     * @param bookmark - representing a domain object
+     * @return - the corresponding domain object
+     */
+    // tag::refguide[]
     Object lookup(Bookmark bookmark);
 
-// end::refguide[]
+    // end::refguide[]
     /**
      * As {@link #lookup(Bookmark)}, but down-casting to the specified type.
      */
-// tag::refguide[]
+    // tag::refguide[]
     default <T> T lookup(Bookmark bookmark, Class<T> cls) {
         return cls.cast(lookup(bookmark));
     }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmarkui/BookmarkUiService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmarkui/BookmarkUiService.java
index e21431b..d94ec32 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmarkui/BookmarkUiService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/bookmarkui/BookmarkUiService.java
@@ -23,6 +23,6 @@ import org.apache.isis.applib.annotation.Programmatic;
 
 // tag::refguide[]
 public interface BookmarkUiService {
-    void clear();                   // <1>
+    void clear();                       // <.>
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java
index 2d441f9..f030cb6 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/Command.java
@@ -105,9 +105,7 @@ public interface Command extends HasUniqueId {
     // end::refguide[]
 
     /**
-     *
      * The date/time at which this command was created.
-     *
      */
     // tag::refguide[]
     Timestamp getTimestamp();                   // <.>
@@ -118,13 +116,13 @@ public interface Command extends HasUniqueId {
      *
      * <p>
      * Will only be populated if a {@link BookmarkService} has been configured.
+     * </p>
      */
     // tag::refguide[]
     Bookmark getTarget();                       // <.>
     // end::refguide[]
 
     /**
-     *
      * Holds a string representation of the invoked action, or the edited property, equivalent to
      * {@link Identifier#toClassAndNameIdentityString()}.
      */
@@ -133,7 +131,6 @@ public interface Command extends HasUniqueId {
     // end::refguide[]
 
     /**
-     *
      * A human-friendly description of the class of the target object.
      */
     // tag::refguide[]
@@ -141,19 +138,13 @@ public interface Command extends HasUniqueId {
     // end::refguide[]
 
     /**
-     *
      * The human-friendly name of the action invoked/property edited on the target object.
-     *
-     * <p>
-     *     NB: in earlier versions, if the command represented an edit of a property, then it held the special value &quot;{@value ACTION_IDENTIFIER_FOR_EDIT}&quot;.  This is NO LONGER the case; it simply holds the member.
-     * </p>
      */
     // tag::refguide[]
     String getTargetAction();                   // <.>
     // end::refguide[]
 
     /**
-     *
      * A human-friendly description of the arguments with which the action was invoked.
      */
     // tag::refguide[]
@@ -390,7 +381,7 @@ public interface Command extends HasUniqueId {
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
-        void setExecutor(final Executor executor);   
+        void setExecutor(final Executor executor);
 
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java
index 1eb6f24..2f7b4d0 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandContext.java
@@ -53,7 +53,7 @@ import lombok.extern.log4j.Log4j2;
 @Log4j2
 public class CommandContext {
 
-// end::refguide[]
+    // end::refguide[]
     public CommandContext() {
         log.debug("init");
     }
@@ -68,24 +68,23 @@ public class CommandContext {
         log.debug("preDestroy");
     }
 
-// tag::refguide[]
+    // tag::refguide[]
     @Getter
     private Command command;
 
-// end::refguide[]
+    // end::refguide[]
     /**
      * <b>NOT API</b>: intended to be called only by the framework.
      */
     public void setCommand(final Command command) {
         this.command = command;
     }
-    
+
     public Optional<Executor> getCurrentExecutor() {
         return Optional.ofNullable(getCommand())
-                .map(Command::getExecutor); 
+                .map(Command::getExecutor);
     }
-    
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandExecutorService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandExecutorService.java
index cfffa0a..917a4e5 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandExecutorService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/CommandExecutorService.java
@@ -21,16 +21,25 @@ package org.apache.isis.applib.services.command;
 // tag::refguide[]
 public interface CommandExecutorService {
 
+    // end::refguide[]
+    // tag::refguide-2[]
     enum SudoPolicy {
+
+        // end::refguide-2[]
         /**
          * For example, regular background commands.
          */
+        // tag::refguide-2[]
         NO_SWITCH,
+
+        // end::refguide-2[]
         /**
          * For example, replayable commands.
          */
+        // tag::refguide-2[]
         SWITCH,
     }
+    // end::refguide-2[]
 
     /**
      * Executes the specified command.
@@ -39,7 +48,11 @@ public interface CommandExecutorService {
      * @param commandWithDto
      * @return - any exception raised by the command.
      */
-    void executeCommand(SudoPolicy sudoPolicy, CommandWithDto commandWithDto);
+    // tag::refguide[]
+    void executeCommand(
+            SudoPolicy sudoPolicy,              // <.>
+            CommandWithDto commandWithDto       // <.>
+    );
 
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java
index 8afa756..eb3abce 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/command/spi/CommandService.java
@@ -26,7 +26,7 @@ import org.apache.isis.applib.services.command.Command;
 // tag::refguide[]
 public interface CommandService {
 
-// end::refguide[]
+    // end::refguide[]
     /**
      * Simply instantiates the appropriate instance of the {@link Command}.
      *
@@ -35,17 +35,17 @@ public interface CommandService {
      * {@link Command#getTimestamp()}, {@link Command#getUser()} and {@link Command#getUniqueId()}).
      * </p>
      */
-// tag::refguide[]
+    // tag::refguide[]
     Command create();                               // <.>
-// end::refguide[]
+    // end::refguide[]
 
     /**
      * Hint for this implementation to eagerly persist the {@link Command}s if possible; influences the behaviour
      * of actions annotated to execute in the {@link org.apache.isis.applib.annotation.CommandExecuteIn#BACKGROUND}.
      */
-// tag::refguide[]
+    // tag::refguide[]
     boolean persistIfPossible(Command command);     // <.>
-// end::refguide[]
+    // end::refguide[]
 
     /**
      * &quot;Complete&quot; the command, typically meaning to indicate that the command is completed, and to
@@ -59,7 +59,7 @@ public interface CommandService {
      *     The framework will automatically have set the {@link Command#getCompletedAt()} property.
      * </p>
      */
-// tag::refguide[]
+    // tag::refguide[]
     void complete(final Command command);           // <.>
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java
index cbbd0e6..7e83574 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationMenu.java
@@ -40,7 +40,7 @@ public class ConfigurationMenu {
 
     // end::refguide[]
     public static abstract class ActionDomainEvent
-        extends IsisModuleApplib.ActionDomainEvent<ConfigurationMenu> {}
+            extends IsisModuleApplib.ActionDomainEvent<ConfigurationMenu> {}
 
     private final ConfigurationViewService configurationService;
 
@@ -50,16 +50,16 @@ public class ConfigurationMenu {
     }
 
     public static class ConfigurationDomainEvent
-        extends ActionDomainEvent {}
+            extends ActionDomainEvent {}
 
     // tag::refguide[]
     @Action(
             domainEvent = ConfigurationDomainEvent.class,
             semantics = SemanticsOf.SAFE
-            )
+    )
     @ActionLayout(
             cssClassFa = "fa-wrench"
-            )
+    )
     @MemberOrder(sequence = "500.900.1")
     public Set<ConfigurationProperty> configuration(){
         return configurationService.allProperties();
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationViewService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationViewService.java
index bc71130..9627c0f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationViewService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/confview/ConfigurationViewService.java
@@ -26,10 +26,12 @@ import org.apache.isis.applib.annotation.Programmatic;
 // tag::refguide[]
 public interface ConfigurationViewService {
 
+    // end::refguide[]
     /**
      * Returns all properties, each as an instance of {@link ConfigurationProperty} (a view model).
      * Mask sensitive values if required.
      */
+    // tag::refguide[]
     Set<ConfigurationProperty> allProperties();
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/conmap/ContentMappingService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/conmap/ContentMappingService.java
index c95ad15..369349e 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/conmap/ContentMappingService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/conmap/ContentMappingService.java
@@ -30,15 +30,18 @@ import org.apache.isis.core.commons.internal.base._NullSafe;
 // tag::refguide[]
 public interface ContentMappingService {
 
+    // end::refguide[]
     /**
      * Typically for mapping from a domain object to a DTO.
      */
+    // tag::refguide[]
     Object map(Object object, final List<MediaType> acceptableMediaTypes);
 
-// end::refguide[]
+    // end::refguide[]
     /**
      * Convenience utilities for implementations of {@link ContentMappingService}.
      */
+    // tag::refguide-2[]
     public static class Util {
 
         public static String determineDomainType(final List<MediaType> acceptableMediaTypes) {
@@ -64,7 +67,8 @@ public interface ContentMappingService {
             return clazz.getName().equals(domainType);
         }
     }
+    // end::refguide-2[]
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/email/EmailService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/email/EmailService.java
index be7f54d..e5960e7 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/email/EmailService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/email/EmailService.java
@@ -37,20 +37,16 @@ import org.apache.isis.applib.annotation.Programmatic;
 // tag::refguide[]
 public interface EmailService extends Serializable {
 
-    /**
-     * Always called by the framework, and allows the implementation to read configuration properties and initialize itself
-     */
     @PostConstruct
     public void init() ;
 
-    /**
-     * Main API to send email and optional attachments.
-     */
     boolean send(List<String> to, List<String> cc, List<String> bcc, String subject, String body, DataSource... attachments);
 
+    // end::refguide[]
     /**
      * Whether this service has been configured and thus available for use.
      */
+    // tag::refguide[]
     boolean isConfigured();
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/error/Ticket.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/error/Ticket.java
index 0d55843..dca850f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/error/Ticket.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/error/Ticket.java
@@ -34,10 +34,13 @@ import java.io.Serializable;
 // tag::refguide[]
 public interface Ticket extends Serializable {
 
+    // end::refguide[]
+    // tag::refguide-2[]
     enum StackTracePolicy {
         SHOW,
         HIDE
     }
+    // end::refguide-2[]
 
     /**
      * A unique identifier that the end-user can use to track any follow-up from this error.
@@ -47,8 +50,10 @@ public interface Ticket extends Serializable {
      *     which case the {@link #getReference() reference} would be the JIRA issue number <tt>XXX-1234</tt>.
      * </p>
      */
+    // tag::refguide[]
     String getReference();
 
+    // end::refguide[]
     /**
      * Message to display to the user.
      *
@@ -56,8 +61,10 @@ public interface Ticket extends Serializable {
      *     Typically this message should be short, one line long.
      * </p>
      */
+    // tag::refguide[]
     String getUserMessage();
 
+    // end::refguide[]
     /**
      * Optional additional details to show to the end-user.
      *
@@ -66,8 +73,10 @@ public interface Ticket extends Serializable {
      *     details on contacting the help desk if the issue is severe and requires immediate attention.
      * </p>
      */
+    // tag::refguide[]
     String getDetails();
 
+    // end::refguide[]
     /**
      * Whether the stack trace for the exception should be displayed or be hidden.
      *
@@ -76,11 +85,14 @@ public interface Ticket extends Serializable {
      *     the support team, meaning there's no need to expose this info to the end-user.
      * </p>
      */
+    // tag::refguide[]
     StackTracePolicy getStackTracePolicy();
 
+    // end::refguide[]
     /**
      * Returns a Html representation of this ticket.
      */
+    // tag::refguide[]
     String getMarkup();
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java
index c5ca151..8c75c23 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizer.java
@@ -61,63 +61,86 @@ import lombok.val;
 // tag::refguide[]
 public interface ExceptionRecognizer {
 
+    // end::refguide[]
     /**
      * (Attempt to) recognize the exception and return a user-friendly
-     * message to render instead. 
+     * message to render instead.
      *
-     * @return optionally a 
-     * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition recognition} object, 
-     * that describes both the 
-     * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category category} 
-     * and reason that will be included with the user-friendly message. 
+     * @return optionally a
+     * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition recognition} object,
+     * that describes both the
+     * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category category}
+     * and reason that will be included with the user-friendly message.
      */
+    // tag::refguide[]
     Optional<Recognition> recognize(Throwable ex);
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     @RequiredArgsConstructor
     enum Category {
+
+        // end::refguide-1[]
         /**
          * A violation of some declarative constraint (eg uniqueness or referential integrity) was detected.
          */
+        // tag::refguide-1[]
         CONSTRAINT_VIOLATION("violation of some declarative constraint"),
+
+        // end::refguide-1[]
         /**
          * The object to be acted upon cannot be found (404)
          */
+        // tag::refguide-1[]
         NOT_FOUND("object not found"),
+
+        // end::refguide-1[]
         /**
          * A concurrency exception, in other words some other user has changed this object.
          */
+        // tag::refguide-1[]
         CONCURRENCY("concurrent modification"),
+
+        // end::refguide-1[]
         /**
          * Recognized, but for some other reason... 40x error
          */
+        // tag::refguide-1[]
         CLIENT_ERROR("client side error"),
+
+        // end::refguide-1[]
         /**
          * 50x error
          */
+        // tag::refguide-1[]
         SERVER_ERROR("server side error"),
+
+        // end::refguide-1[]
         /**
          * Recognized, but uncategorized (typically: a recognizer of the original ExceptionRecognizer API).
          */
+        // tag::refguide-1[]
         OTHER("other")
         ;
-        
+
         @Getter
         private final String friendlyName;
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide-2[]
+    // tag::refguide-2[]
     @Value
     class Recognition {
 
+        // end::refguide-2[]
         /**
          * @return optionally a recognition of the specified type, based on a whether given reason is non-null
          */
+        // tag::refguide-2[]
         public static Optional<Recognition> of(
                 @Nullable final Category category,
                 @Nullable final String reason) {
+            // end::refguide-2[]
 
             if(reason==null) {
                 return Optional.empty();
@@ -125,27 +148,34 @@ public interface ExceptionRecognizer {
 
             val nonNullCategory = category!=null? category: Category.OTHER;
             return Optional.of(new Recognition(nonNullCategory, reason));
+            // tag::refguide-2[]
+            // ...
         }
 
         @NonNull private final Category category;
         @NonNull private final String reason;
 
         public String toMessage(@Nullable TranslationService translationService) {
-            
+            // end::refguide-2[]
+
             val categoryLiteral = translationService!=null
                     ? translationService.translate(
                             ExceptionRecognizer.Category.class.getName(), getCategory().getFriendlyName())
                             : getCategory().getFriendlyName();
-                            
+
             val reasonLiteral = translationService!=null
                     ? translationService.translate(
                             ExceptionRecognizer.Recognition.class.getName(), getReason())
                             : getReason();
-            
+
             return String.format("[%s]: %s", categoryLiteral, reasonLiteral);
+            // tag::refguide-2[]
+            // ...
         }
+        // end::refguide-2[]
     }
-// end::refguide-2[]
-// tag::refguide[]
+    // end::refguide-2[]
+
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java
index 64e0edd..2c8043b 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/ExceptionRecognizerService.java
@@ -31,31 +31,38 @@ import org.apache.isis.core.commons.collections.Can;
 // tag::refguide[]
 public interface ExceptionRecognizerService {
 
+    // end::refguide[]
     /**
-     * 
-     * @return all ExceptionRecognizer implementations as discovered by the IoC container, 
-     * honoring order of precedence. 
+     *
+     * @return all ExceptionRecognizer implementations as discovered by the IoC container,
+     * honoring order of precedence.
      */
+    // tag::refguide[]
     Can<ExceptionRecognizer> getExceptionRecognizers();
 
+    // end::refguide[]
     /**
      * Takes into consideration ExceptionRecognizers as given by {@link #getExceptionRecognizers()}.
      *
-     * @param ex
-     * @return optionally a recognition object, that describes both the category and reason, 
-     * that will be included with the user-friendly message. 
+     * @param ex - exception to be recognized
+     * @return optionally a recognition object, that describes both the category and reason,
+     * that will be included with the user-friendly message.
      */
+    // tag::refguide[]
     default Optional<Recognition> recognize(Exception ex) {
         return recognizeFromSelected(getExceptionRecognizers(), ex);
     }
 
+    // end::refguide[]
     /**
      * Takes into consideration ExceptionRecognizers as given by {@code recognizers}.
-     * @param recognizers
-     * @param ex
-     * @return optionally a recognition object, that describes both the category and reason, 
-     * that will be included with the user-friendly message. 
+     *
+     * @param recognizers - one or more recognizers to attempt to recognize the exceptoin
+     * @param ex - the exception to be recognized
+     * @return optionally a recognition object, that describes both the category and reason,
+     * that will be included with the user-friendly message.
      */
+    // tag::refguide[]
     Optional<Recognition> recognizeFromSelected(Can<ExceptionRecognizer> recognizers, Exception ex);
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/TranslatableException.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/TranslatableException.java
index 58e27e4..1e70cbc 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/TranslatableException.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/exceprecog/TranslatableException.java
@@ -33,6 +33,7 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
 // tag::refguide[]
 public interface TranslatableException {
 
+    // end::refguide[]
     /**
      * In the spirit of {@link Exception#getLocalizedMessage()}, but using {@link org.apache.isis.applib.services.i18n.TranslatableString} instead.
      *
@@ -43,12 +44,15 @@ public interface TranslatableException {
      *     accept a {@link org.apache.isis.applib.services.i18n.TranslatableString}, but can be left as null for any existing code.
      * </p>
      */
+    // tag::refguide[]
     TranslatableString getTranslatableMessage();
 
+    // end::refguide[]
     /**
      * The context to use when translating the {@link #getTranslatableMessage() translatable message},
      * as ultimately passed through to {@link org.apache.isis.applib.services.i18n.TranslationService#translate(String, String)}.
      */
+    // tag::refguide[]
     String getTranslationContext();
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/factory/FactoryService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/factory/FactoryService.java
index b03a26e..e09fdf6 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/factory/FactoryService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/factory/FactoryService.java
@@ -23,17 +23,19 @@ import java.util.NoSuchElementException;
 
 import javax.annotation.Nullable;
 
+import org.apache.isis.applib.services.repository.RepositoryService;
 import org.apache.isis.core.commons.exceptions.IsisException;
 
 // tag::refguide[]
 public interface FactoryService {
 
+    // end::refguide[]
     /**
      * General purpose factory method, to automatically get or create an instance of
      * {@code requiredType}.
      *
      * <p>
-     * Maps onto one of the specialized factory methods {@link #get(Class)} or {@link #create(Class)} 
+     * Maps onto one of the specialized factory methods {@link #get(Class)} or {@link #create(Class)}
      * based on the type's meta-data.
      * </p>
      *
@@ -47,40 +49,48 @@ public interface FactoryService {
      * @since 2.0
      *
      */
+    // tag::refguide[]
     <T> T getOrCreate(Class<T> requiredType);
 
+    // end::refguide[]
     /**
-     * Gets an instance (possibly shared or independent) of the specified {@code requiredType}, 
-     * with injection points resolved 
+     * Gets an instance (possibly shared or independent) of the specified {@code requiredType},
+     * with injection points resolved
      * and any life-cycle callback processed.
-     * 
+     *
      * @param <T>
      * @param requiredType - only applicable to IoC container managed types
      * @return (non-null), an instance of {@code requiredType}, if available and unique
      * (i.e. not multiple candidates found with none marked as primary)
-     * 
+     *
      * @throws NoSuchElementException if result is empty
      * @throws IsisException if instance creation failed
-     * 
+     *
      * @apiNote does not force the requiredType to be added to the meta-model
      * @since 2.0
      */
+    // tag::refguide[]
     <T> T get(Class<T> requiredType);
 
+    // end::refguide[]
     /**
      * Creates a new detached entity instance, with injection points resolved
      * and defaults applied.
+     *
      * @param <T>
      * @param domainClass - only applicable to entity types
      * @return
-     * @throws IllegalArgumentException if domainClass is not an entity type  
+     * @throws IllegalArgumentException if domainClass is not an entity type
      * @apiNote forces the domainClass to be added to the meta-model if not already
      * @since 2.0
      */
+    // tag::refguide[]
     <T> T detachedEntity(Class<T> domainClass);
 
+    // end::refguide[]
     /**
      * Creates a new Mixin instance, with injection points resolved.
+     *
      * @param <T>
      * @param mixinClass
      * @param mixedIn
@@ -88,44 +98,52 @@ public interface FactoryService {
      * @throws IllegalArgumentException if mixinClass is not a mixin type
      * @apiNote forces the mixinClass to be added to the meta-model if not already
      */
+    // tag::refguide[]
     <T> T mixin(Class<T> mixinClass, Object mixedIn);
 
+    // end::refguide[]
     /**
-     * Creates a new ViewModel instance, with injection points resolved, 
-     * and initialized according to the given {@code mementoStr} 
+     * Creates a new ViewModel instance, with injection points resolved,
+     * and initialized according to the given {@code mementoStr}
+     *
      * @param viewModelClass
      * @param mementoStr - ignored if {@code null}
      * @throws IllegalArgumentException if viewModelClass is not a viewmodel type
      * @apiNote forces the viewModelClass to be added to the meta-model if not already
      * @since 2.0
      */
+    // tag::refguide[]
     <T> T viewModel(Class<T> viewModelClass, @Nullable String mementoStr);
 
+    // end::refguide[]
     /**
-     * Creates a new ViewModel instance, 
+     * Creates a new ViewModel instance,
      * with injection points resolved
-     * and defaults applied. 
+     * and defaults applied.
      * @param viewModelClass
      * @throws IllegalArgumentException if viewModelClass is not a viewmodel type
      * @apiNote forces the viewModelClass to be added to the meta-model if not already
      * @since 2.0
      */
+    // tag::refguide[]
     default <T> T viewModel(Class<T> viewModelClass) {
         return viewModel(viewModelClass, /*mementoStr*/null);
     }
 
+    // end::refguide[]
     /**
-     * Creates a new instance of the specified class, 
+     * Creates a new instance of the specified class,
      * with injection points resolved
      * and defaults applied.
      * @param domainClass - not applicable to IoC container managed types
-     * @throws IllegalArgumentException if domainClass is an IoC container managed type, 
+     * @throws IllegalArgumentException if domainClass is an IoC container managed type,
      *      or not recognized by the meta-model
      * @apiNote forces the domainClass to be added to the meta-model if not already
      * @since 2.0
      */
+    // tag::refguide[]
     <T> T create(Class<T> domainClass);
-// end::refguide[]
+    // end::refguide[]
 
     // -- DEPRECATIONS
 
@@ -156,8 +174,8 @@ public interface FactoryService {
      * alternatively just <i>new()</i> up the object rather than call this
      * method.
      * </p>
-     * @deprecated with semantic changes since 2.0 previous behavior is no longer guaranteed, 
-     * instead consider use of @{@link #detachedEntity(Class)} or {@link #getOrCreate(Class)} 
+     * @deprecated with semantic changes since 2.0 previous behavior is no longer guaranteed,
+     * instead consider use of @{@link #detachedEntity(Class)} or {@link #getOrCreate(Class)}
      * if applicable
      */
     @Deprecated
@@ -165,6 +183,6 @@ public interface FactoryService {
         return getOrCreate(domainClass);
     }
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridLoaderService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridLoaderService.java
index 7828441..202eb65 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridLoaderService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridLoaderService.java
@@ -24,31 +24,41 @@ import org.apache.isis.applib.layout.grid.Grid;
 // tag::refguide[]
 public interface GridLoaderService {
 
+    // end::refguide[]
     /**
      * Whether dynamic reloading of layouts is enabled.
      */
+    // tag::refguide[]
     boolean supportsReloading();
 
+    // end::refguide[]
     /**
      * To support metamodel invalidation/rebuilding of spec.
      */
+    // tag::refguide[]
     void remove(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Whether any persisted layout metadata (eg a <code>.layout.xml</code> file) exists for this domain class.
      */
+    // tag::refguide[]
     boolean existsFor(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Returns a new instance of a {@link Grid} for the specified domain class, eg from a
      * <code>layout.xml</code> file, else <code>null</code>.
      */
+    // tag::refguide[]
     Grid load(final Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Returns a new instance of a {@link Grid} for the specified domain class, eg from a
      * <code>layout.xml</code> file, else <code>null</code>.
      */
+    // tag::refguide[]
     Grid load(final Class<?> domainClass, String layout);
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridService.java
index bdfa20a..f9db3c5 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridService.java
@@ -29,32 +29,43 @@ import org.apache.isis.applib.layout.grid.Grid;
 // tag::refguide[]
 public interface GridService {
 
+    // end::refguide[]
     /**
      * Whether dynamic reloading of layouts is enabled.
      */
+    // tag::refguide[]
     boolean supportsReloading();
 
+    // end::refguide[]
     /**
      * To support metamodel invalidation/rebuilding of spec.
      */
+    // tag::refguide[]
     void remove(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Whether any persisted layout metadata (eg a <code>.layout.xml</code> file) exists for this domain class.
      */
+    // tag::refguide[]
     boolean existsFor(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Returns a new instance of a {@link Grid} for the specified domain class, eg from a
      * <code>layout.xml</code> file, else <code>null</code>.
      */
+    // tag::refguide[]
     Grid load(final Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Returns a default grid; eg where none can be loaded using {@link #load(Class)}.
      */
+    // tag::refguide[]
     Grid defaultGridFor(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Returns a normalized grid for the domain class obtained previously using {@link #load(Class)}.
      *
@@ -69,8 +80,10 @@ public interface GridService {
      *     <code>layout.xml</code> file takes precedence over any annotations.
      * </p>
      */
+    // tag::refguide[]
     Grid normalize(final Grid grid);
 
+    // end::refguide[]
     /**
      * Modifies the provided {@link Grid} with additional metadata, broadly speaking corresponding to the
      * {@link DomainObjectLayout}, {@link ActionLayout}, {@link PropertyLayout} and {@link CollectionLayout}.
@@ -81,8 +94,10 @@ public interface GridService {
      *     to be required in the domain class itself.
      * </p>
      */
+    // tag::refguide[]
     Grid complete(Grid grid);
 
+    // end::refguide[]
     /**
      * Modifies the provided {@link Grid}, removing all metadata except the basic grid structure.
      *
@@ -95,12 +110,15 @@ public interface GridService {
      * @param grid
      * @return
      */
+    // tag::refguide[]
     Grid minimal(Grid grid);
 
+    // end::refguide[]
     /**
      * Returns a new instance of a {@link Grid} for the specified domain class, eg from a
      * <code>[domainClass].layout.[layout].xml</code> file, else <code>null</code>.
      */
+    // tag::refguide[]
     Grid load(Class<?> domainClass, String layout);
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridSystemService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridSystemService.java
index bdeab5d..5a2c289 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridSystemService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/grid/GridSystemService.java
@@ -27,9 +27,11 @@ import org.apache.isis.applib.layout.grid.Grid;
 // tag::refguide[]
 public interface GridSystemService<G extends Grid> {
 
+    // end::refguide[]
     /**
      * Which grid (implementation) is defined by this service.
      */
+    // tag::refguide[]
     Class<G> gridImplementation();
 
     String tns();
@@ -38,10 +40,12 @@ public interface GridSystemService<G extends Grid> {
 
     G defaultGrid(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Validate the grid, derive any missing object members, and overwrite any facets in the metamodel based on the
      * layout.
      */
+    // tag::refguide[]
     void normalize(G grid, Class<?> domainClass);
 
     void complete(G grid, Class<?> domainClass);
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/Health.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/Health.java
index 82c7dda..c908630 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/Health.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/health/Health.java
@@ -21,6 +21,7 @@ package org.apache.isis.applib.services.health;
 import lombok.AllArgsConstructor;
 import lombok.Getter;
 
+// tag::refguide[]
 @AllArgsConstructor
 public class Health {
 
@@ -41,3 +42,4 @@ public class Health {
 
     public boolean getResult() { return message == null; }
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/hint/HintStore.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/hint/HintStore.java
index da2d21e..8572827 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/hint/HintStore.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/hint/HintStore.java
@@ -26,13 +26,13 @@ import org.apache.isis.applib.services.bookmark.Bookmark;
 // tag::refguide[]
 public interface HintStore {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     interface HintIdProvider {
         String hintId();
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-1[]
+    // tag::refguide[]
 
     String get(final Bookmark bookmark, String hintKey);
 
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/HomePageResolverService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/HomePageResolverService.java
index 263ae0e..a4a7f6b 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/HomePageResolverService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/HomePageResolverService.java
@@ -22,6 +22,7 @@ import org.apache.isis.applib.annotation.HomePage;
 
 /**
  * Returns a view model annotated with {@link HomePage}.
+ *
  * @since 2.0
  */
 // tag::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/package-info.java
similarity index 77%
copy from api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
copy to api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/package-info.java
index 0ba797f..2bb38af 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/homepage/package-info.java
@@ -16,12 +16,9 @@
  *  specific language governing permissions and limitations
  *  under the License.
  */
-package org.apache.isis.applib.services.metamodel;
 
-import java.util.List;
-
-public interface DomainModel {
-
-    List<DomainMember> getDomainMembers();
-
-}
+/**
+ * The {@link org.apache.isis.applib.services.homepage.HomePageResolverService} returns the view model, if any
+ * annotated with {@link org.apache.isis.applib.annotation.HomePage}.
+ */
+package org.apache.isis.applib.services.homepage;
\ No newline at end of file
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslatableString.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslatableString.java
index 8f8f1f9..30de466 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslatableString.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslatableString.java
@@ -28,9 +28,11 @@ import org.apache.isis.applib.annotation.Programmatic;
 import org.apache.isis.applib.annotation.Value;
 import org.apache.isis.core.commons.internal.collections._Lists;
 
+// tag::refguide[]
 @Value
 public final class TranslatableString {
 
+    // end::refguide[]
     // -- tr, trn (factory methods); constructor
 
     /**
@@ -39,15 +41,22 @@ public final class TranslatableString {
      * @param pattern - pattern for all (singular and plural) form, with <code>${xxx}</code> placeholders
      * @param paramArgs - parameter/argument pairs (string and object, string and object, ...)
      */
+    // tag::refguide[]
     public static TranslatableString tr(
             final String pattern,
             final Object... paramArgs) {
+        // end::refguide[]
+
         if(pattern == null) {
             return null;
         }
         return new TranslatableString(Type.TR, pattern, null, 1, asMap(paramArgs));
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * A translatable string with different patterns for singular and plural forms, selected automatically by the number
      *
@@ -56,14 +65,20 @@ public final class TranslatableString {
      * @param number - whether to use singular or plural form when rendering
      * @param paramArgs - parameter/argument pairs (string and object, string and object, ...)
      */
+    // tag::refguide[]
     public static TranslatableString trn(
             final String singularPattern,
             final String pluralPattern,
             final int number,
             final Object... paramArgs) {
+
         return new TranslatableString(Type.TRN, singularPattern, pluralPattern, number, asMap(paramArgs));
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * Converts a list of objects [a, 1, b, 2] into a map {a -> 1; b -> 2}
      */
@@ -181,8 +196,9 @@ public final class TranslatableString {
      * @param context
      * @return
      */
-    @Programmatic
+    // tag::refguide[]
     public String translate(final TranslationService translationService, final String context) {
+
         final String translatedText =
                 !isPluralForm()
                 ? translationService.translate(context, getSingularText())
@@ -190,6 +206,7 @@ public final class TranslatableString {
                 return translated(translatedText);
     }
 
+    // end::refguide[]
     /**
      * The text to be translated; depends on whether {@link #isPluralForm()} and whether to be translated.
      *
@@ -203,10 +220,11 @@ public final class TranslatableString {
      *     {@link Exception#getMessage() message} when only a translatable message has been provided.
      * </p>
      */
-    @Programmatic
+    // tag::refguide[]
     public String getPattern() {
         return !isPluralForm() || number == 1 ? getSingularText() : getPluralText();
     }
+    // end::refguide[]
 
     String translated(final String translatedText) {
         return format(translatedText, argumentsByParameterName);
@@ -269,6 +287,6 @@ public final class TranslatableString {
         return type.toString(this);
     }
 
-
-
+    // tag::refguide[]
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslationService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslationService.java
index 17e791e..5f55e2f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslationService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/i18n/TranslationService.java
@@ -24,6 +24,7 @@ import java.util.function.Predicate;
 // tag::refguide[]
 public interface TranslationService {
 
+    // end::refguide[]
     /**
      * Return a translation of the text, in the locale of the &quot;current user&quot;.
      *
@@ -35,8 +36,10 @@ public interface TranslationService {
      * @param text
      * @return
      */
+    // tag::refguide[]
     String translate(final String context, final String text);
 
+    // end::refguide[]
     /**
      * Return a translation of either the singular or the plural text, dependent on the <tt>num</tt> parameter,
      * in the locale of the &quot;current user&quot;.
@@ -51,23 +54,48 @@ public interface TranslationService {
      * @param num - whether to return the translation of the singular (if =1) or of the plural (if != 1)
      * @return
      */
+    // tag::refguide[]
     String translate(final String context, final String singularText, final String pluralText, int num);
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     enum Mode {
-        DISABLED(configValue->configValue != null &&
-                ("disable".equalsIgnoreCase(configValue) ||
-                        "disabled".equalsIgnoreCase(configValue))),
+
+        DISABLED (
+            // end::refguide-1[]
+                configValue->
+                    ("disable".equalsIgnoreCase(configValue) ||
+                     "disabled".equalsIgnoreCase(configValue))
+            // tag::refguide-1[]
+            // ...
+        ),
 
         // synonym, needs to be defined, such that config beans (since 2.0) do work
-        DISABLE(configValue->false),
+        DISABLE(
+            // end::refguide-1[]
+                configValue->false
+            // tag::refguide-1[]
+            // ...
+        ),
+
+        READ(
+            // end::refguide-1[]
+                configValue->
+                    ("read".equalsIgnoreCase(configValue) ||
+                     "reader".equalsIgnoreCase(configValue))
+            // tag::refguide-1[]
+            // ...
+        ),
 
-        READ(configValue->configValue != null &&
-        ("read".equalsIgnoreCase(configValue) ||
-                "reader".equalsIgnoreCase(configValue))),
-        // default
-        WRITE(configValue->!READ.matches(configValue) && !DISABLED.matches(configValue));
+        WRITE(
+            // end::refguide-1[]
+                configValue ->
+                    !READ.matches(configValue) &&
+                    !DISABLED.matches(configValue)
+            // tag::refguide-1[]
+            // ...
+        );
+        // end::refguide-1[]
 
         // -- handle values from configuration
 
@@ -90,9 +118,10 @@ public interface TranslationService {
         public boolean isDisabled() {
             return this == DISABLED || this == DISABLE;
         }
+
+        // tag::refguide-1[]
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-1[]
 
     /**
      * Whether this implementation is operating in read or in write mode.
@@ -112,6 +141,8 @@ public interface TranslationService {
      *     such that all pathways are exercised..
      * </p>
      */
+    // tag::refguide[]
     Mode getMode();
+
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/Interaction.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/Interaction.java
index 65a2112..c65f26f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/Interaction.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/Interaction.java
@@ -84,11 +84,12 @@ import lombok.extern.log4j.Log4j2;
 @Log4j2
 public class Interaction implements HasUniqueId {
 
-
     @Getter @Setter
     private UUID uniqueId;
+    // end::refguide[]
 
     private final List<Execution<?,?>> executionGraphs = _Lists.newArrayList();
+
     /**
      * Returns a (list of) {@link Execution}s in the order that they were pushed.  Generally there will be just one entry in this list, but additional entries may arise from the use of mixins/contributions when re-rendering a modified object.
      *
@@ -105,23 +106,33 @@ public class Interaction implements HasUniqueId {
      *  {@link #execute(MemberExecutor, ActionInvocation, ClockService, MetricsService)} for us, to ensure that the
      *  graph is populated, but then delegate to the PublisherService immediately at the end... ie {@link org.apache.isis.schema.ixn.v2.InteractionDto}s are published as we go, not all in a batch at the end.
      */
+    // tag::refguide[]
     public List<Execution<?,?>> getExecutions() {
+        // end::refguide[]
+
         return Collections.unmodifiableList(executionGraphs);
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * The current (most recently pushed) {@link Execution}.
      */
+    // tag::refguide[]
     @Getter
     private Execution<?,?> currentExecution;
 
+    // end::refguide[]
     /**
      * The execution that preceded the current one.
      */
+    // tag::refguide[]
     @Getter
     private Execution<?,?> priorExecution;
 
-// end::refguide[]
+    // end::refguide[]
     /**
      * <b>NOT API</b>: intended to be called only by the framework.
      *
@@ -270,51 +281,69 @@ public class Interaction implements HasUniqueId {
     }
 
 
-// tag::refguide-1[]
     /**
      * Enumerates the different reasons why multiple occurrences of a certain type might occur within a single
      * (top-level) interaction.
      */
+    // tag::refguide-1[]
     public enum Sequence {
 
+        // end::refguide-1[]
         /**
          * Each interaction is either an action invocation or a property edit.  There could be multiple of these,
          * typically as the result of a nested calls using the {@link WrapperFactory}.  Another reason is
          * support for bulk action invocations within a single transaction.
          */
+        // tag::refguide-1[]
         INTERACTION,
+
+        // end::refguide-1[]
         /**
          * For objects: multiple such could be dirtied and thus published as separate events.  For actions
          * invocations/property edits : multiple sub-invocations could occur if sub-invocations are made through the
          * {@link WrapperFactory}.
          */
+        // tag::refguide-1[]
         PUBLISHED_EVENT,
+
+        // end::refguide-1[]
         /**
          * There may be multiple transactions within a given interaction.
          */
+        // tag::refguide-1[]
         TRANSACTION,
         ;
+        // end::refguide-1[]
 
         public String id() {
             return Interaction.Sequence.class.getName() + "#" + name();
         }
+        // tag::refguide-1[]
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide[]
+    // tag::refguide[]
     private final Map<String, LongAdder> maxBySequence = _Maps.newHashMap();
 
+    // end::refguide[]
     /**
-     * Generates numbers in a named sequence.  The name of the sequence can be arbitrary, though note that the
-     * framework also uses this capability to generate sequence numbers corresponding to the sequences enumerated by
-     * the {@link Sequence} enum.
+     * Generates numbers in a named sequence.
+     *
+     * The name of the sequence can be arbitrary, though note that the framework also uses this capability to
+     * generate sequence numbers corresponding to the sequences enumerated by the {@link Sequence} enum.
      */
+    // tag::refguide[]
     public int next(final String sequenceId) {
+        // end::refguide[]
+
         final LongAdder adder = maxBySequence.computeIfAbsent(sequenceId, this::newAdder);
         adder.increment();
         return adder.intValue();
+
+        // tag::refguide[]
+        // ...
     }
-// end::refguide[]
+    // end::refguide[]
 
     private LongAdder newAdder(String ignore) {
         final LongAdder adder = new LongAdder();
@@ -322,38 +351,46 @@ public class Interaction implements HasUniqueId {
         return adder;
     }
 
-// tag::refguide-2[]
     /**
      * Represents an action invocation/property edit as a node in a call-stack execution graph, with sub-interactions
      * being made by way of the {@link WrapperFactory}).
      */
+    // tag::refguide-2[]
     public static abstract class Execution<T extends MemberExecutionDto, E extends AbstractDomainEvent<?>> {
 
-        // -- fields, constructor
-
         @Getter
         private final Interaction interaction;
         @Getter
         private final InteractionType interactionType;
         @Getter
         private final String memberIdentifier;
+
+        // end::refguide-2[]
         /**
          * The target of the action invocation.  If this interaction is for a mixin action, then will be the
          * mixed-in target (not the transient mixin itself).
          */
+        // tag::refguide-2[]
         @Getter
         private final Object target;
+
+        // end::refguide-2[]
         /**
          * A human-friendly description of the class of the target object.
          */
+        // tag::refguide-2[]
         @Getter
         private final String targetClass;
+
+        // end::refguide-2[]
         /**
          * The human-friendly name of the action invoked/property edited on the target object.
          */
+        // tag::refguide-2[]
         @Getter
         private final String targetMember;
 
+        // end::refguide-2[]
         protected Execution(
                 final Interaction interaction,
                 final InteractionType interactionType,
@@ -377,9 +414,11 @@ public class Interaction implements HasUniqueId {
         /**
          * The action/property that invoked this action/property edit (if any).
          */
+        // tag::refguide-2[]
         @Getter
         private Execution<?,?> parent;
 
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
@@ -393,13 +432,17 @@ public class Interaction implements HasUniqueId {
         /**
          * The actions/property edits made in turn via the {@link WrapperFactory}.
          */
+        // tag::refguide-2[]
         public List<Execution<?,?>> getChildren() {
-            return Collections.unmodifiableList(children);
-        }
+            // end::refguide-2[]
 
+            return Collections.unmodifiableList(children);
 
-        // -- event
+            // tag::refguide-2[]
+            // ...
+        }
 
+        // end::refguide-2[]
         /**
          * The domain event fired on the {@link EventBusService event bus} representing the execution of
          * this action invocation/property edit.
@@ -410,9 +453,11 @@ public class Interaction implements HasUniqueId {
          *     {@link AbstractDomainEvent.Phase#EXECUTING executing} phase.
          * </p>
          */
+        // tag::refguide-2[]
         @Getter
         private E event;
 
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
@@ -420,29 +465,35 @@ public class Interaction implements HasUniqueId {
             this.event = event;
         }
 
-
-        // -- startedAt, completedAt
-
         /**
          * The date/time at which this execution started.
          */
+        // tag::refguide-2[]
         @Getter
         private Timestamp startedAt;
 
+        // end::refguide-2[]
         /**
          * The date/time at which this execution completed.
          */
+        // tag::refguide-2[]
         @Getter
         private Timestamp completedAt;
 
         public Timestamp start(
                 final ClockService clockService,
                 final MetricsService metricsService) {
+            // end::refguide-2[]
+
             val startedAt = clockService.nowAsJavaSqlTimestamp();
             syncMetrics(When.BEFORE, startedAt, metricsService);
             return startedAt;
+
+            // tag::refguide-2[]
+            // ...
         }
 
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
@@ -452,7 +503,6 @@ public class Interaction implements HasUniqueId {
             syncMetrics(When.AFTER, completedAt, metricsService);
         }
 
-
         /**
          * The object returned by the action invocation/property edit.
          *
@@ -464,9 +514,11 @@ public class Interaction implements HasUniqueId {
          * For <tt>void</tt> methods and for actions returning collections, the value
          * will be <tt>null</tt>.
          */
+        // tag::refguide-2[]
         @Getter
         private Object returned;
 
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
@@ -474,9 +526,11 @@ public class Interaction implements HasUniqueId {
             this.returned = returned;
         }
 
+        // tag::refguide-2[]
         @Getter
         private Exception threw;
 
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
@@ -496,10 +550,11 @@ public class Interaction implements HasUniqueId {
          *     {@link Execution#getReturned()}) will (obviously) still be null.
          * </p>
          */
+        // tag::refguide-2[]
         @Getter
         private T dto;
 
-
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: Set by framework (implementation of {@link MemberExecutor})
          */
@@ -508,12 +563,13 @@ public class Interaction implements HasUniqueId {
         }
 
 
-
         // -- helpers (syncMetrics)
 
-// tag::refguide-2a[]
+        // tag::refguide-2a[]
         enum When {
             BEFORE {
+                // end::refguide-2a[]
+
                 @Override
                 void syncMetrics(
                         final Execution<?, ?> execution,
@@ -533,8 +589,12 @@ public class Interaction implements HasUniqueId {
                     numberObjectsDirtiedFor(objectCountsDto).setBefore(numberObjectsDirtied);
                 }
 
+                // tag::refguide-2a[]
+                // ....
             },
             AFTER {
+                // end::refguide-2a[]
+
                 @Override void syncMetrics(
                         final Execution<?, ?> execution,
                         final Timestamp timestamp,
@@ -553,7 +613,10 @@ public class Interaction implements HasUniqueId {
                     numberObjectsDirtiedFor(objectCountsDto).setAfter(numberObjectsDirtied);
                 }
 
+                // tag::refguide-2a[]
+                // ....
             };
+            // end::refguide-2a[]
 
             // -- helpers
 
@@ -582,7 +645,10 @@ public class Interaction implements HasUniqueId {
                     final Timestamp timestamp,
                     final int numberObjectsLoaded,
                     final int numberObjectsDirtied);
+            // tag::refguide-2a[]
         }
+        // end::refguide-2a[]
+
         private void syncMetrics(
                 final When when,
                 final Timestamp timestamp,
@@ -593,16 +659,17 @@ public class Interaction implements HasUniqueId {
 
             when.syncMetrics(this, timestamp, numberObjectsLoaded, numberObjectsDirtied);
         }
-// end::refguide-2a[]
 
+        // tag::refguide-2[]
     }
-// end::refguide-2[]
+    // end::refguide-2[]
 
-// tag::refguide-3[]
+    // tag::refguide-3[]
     public static class ActionInvocation extends Execution<ActionInvocationDto, ActionDomainEvent<?>> {
 
         @Getter
         private final List<Object> args;
+        // end::refguide-3[]
 
         public ActionInvocation(
                 final Interaction interaction,
@@ -614,14 +681,17 @@ public class Interaction implements HasUniqueId {
             super(interaction, InteractionType.ACTION_INVOCATION, memberId, target, targetMember, targetClass);
             this.args = args;
         }
+        // tag::refguide-3[]
+        // ...
     }
-// end::refguide-3[]
+    // end::refguide-3[]
 
-// tag::refguide-4[]
+    // tag::refguide-4[]
     public static class PropertyEdit extends Execution<PropertyEditDto, PropertyDomainEvent<?,?>> {
 
         @Getter
         private final Object newValue;
+        // end::refguide-4[]
 
         public PropertyEdit(
                 final Interaction interaction,
@@ -633,9 +703,12 @@ public class Interaction implements HasUniqueId {
             super(interaction, InteractionType.PROPERTY_EDIT, memberId, target, targetMember, targetClass);
             this.newValue = newValue;
         }
+
+        // tag::refguide-4[]
+        // ...
     }
-// end::refguide-4[]
+    // end::refguide-4[]
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java
index a3899aa..b51c596 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/iactn/InteractionContext.java
@@ -51,7 +51,7 @@ import lombok.extern.log4j.Log4j2;
 @Log4j2
 public class InteractionContext {
 
-// end::refguide[]
+    // end::refguide[]
     public InteractionContext() {
         log.debug("init");
     }
@@ -66,13 +66,13 @@ public class InteractionContext {
         log.debug("preDestroy");
     }
 
-// tag::refguide[]
     /**
      * The currently active {@link Interaction} for this thread.
      */
+    // tag::refguide[]
     @Getter
     private Interaction interaction;
-// end::refguide[]
+    // end::refguide[]
 
     /**
      * <b>NOT API</b>: intended to be called only by the framework.
@@ -80,6 +80,7 @@ public class InteractionContext {
     public void setInteraction(final Interaction interaction) {
         this.interaction = interaction;
     }
-// tag::refguide[]
+
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/inject/ServiceInjector.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/inject/ServiceInjector.java
index ea7e137..dcfee4a 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/inject/ServiceInjector.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/inject/ServiceInjector.java
@@ -39,6 +39,8 @@ public interface ServiceInjector {
     <T> T injectServicesInto(final T domainObject, Consumer<InjectionPoint> onNotResolvable);
 
     default <T> T injectServicesInto(final T domainObject) {
+        // end::refguide[]
+
         return injectServicesInto(domainObject, injectionPoint->{
 
             val injectionPointName = injectionPoint.toString();
@@ -51,6 +53,9 @@ public interface ServiceInjector {
             throw new NoSuchElementException(msg);
         });
 
+        // tag::refguide[]
+        // ...
     }
+
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/jaxb/JaxbService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/jaxb/JaxbService.java
index ad86f6a..61bafdc 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/jaxb/JaxbService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/jaxb/JaxbService.java
@@ -47,14 +47,18 @@ public interface JaxbService {
 
     Object fromXml(JAXBContext jaxbContext, String xml, Map<String,Object> unmarshallerProperties);
 
+    // end::refguide[]
     /**
      * As {@link #fromXml(JAXBContext, String)}, but downcast to a specific type.
      */
+    // tag::refguide[]
     <T> T fromXml(Class<T> domainClass, String xml);
 
+    // end::refguide[]
     /**
      * As {@link #fromXml(JAXBContext, String, Map)}, but downcast to a specific type.
      */
+    // tag::refguide[]
     <T> T fromXml(Class<T> domainClass, String xml, Map<String,Object> unmarshallerProperties);
 
     String toXml(final Object domainObject);
@@ -75,10 +79,11 @@ public interface JaxbService {
      *     <a href="http://isis.apache.org/schema">downloaded</a> from the Isis website.
      * </p>
      */
+    // tag::refguide[]
     enum IsisSchemas {
         INCLUDE,
         IGNORE;
-// end::refguide[]
+        // end::refguide[]
 
         /**
          * Implementation note: not using subclasses, otherwise the key in translations.po becomes more complex.
@@ -90,12 +95,12 @@ public interface JaxbService {
                 return namespaceUri.matches(".*isis\\.apache\\.org.*");
             }
         }
-// tag::refguide[]
+        // tag::refguide[]
     }
 
     Map<String, String> toXsd(final Object domainObject, final IsisSchemas isisSchemas);
 
-// end::refguide[]
+    // end::refguide[]
     class Simple implements JaxbService {
 
         @Override
@@ -245,6 +250,7 @@ public interface JaxbService {
             }
         }
     }
-// tag::refguide[]
+
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/layout/LayoutService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/layout/LayoutService.java
index 598cc6c..a0fb471 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/layout/LayoutService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/layout/LayoutService.java
@@ -25,15 +25,17 @@ import org.apache.isis.applib.services.menu.MenuBarsService;
 // tag::refguide[]
 public interface LayoutService {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+
     /**
      * Mode of operation when downloading a layout file (while prototyping). It affects the way the file's
      * content is assembled. Once a layout file is in place, its layout data takes precedence over any
      * conflicting layout data from annotations.
      */
+    // tag::refguide-1[]
     enum Style {
 
+        // end::refguide-1[]
         /**
          * The current layout for the domain class.
          * <p>
@@ -43,8 +45,10 @@ public interface LayoutService {
          * {@link org.apache.isis.applib.services.grid.GridService#defaultGridFor(Class) default grid},
          * also {@link org.apache.isis.applib.services.grid.GridService#normalize(Grid) normalized}.
          */
+        // tag::refguide-1[]
         CURRENT,
 
+        // end::refguide-1[]
         /**
          * As per {@link #NORMALIZED}, but also with all (non-null) facets for all
          * properties/collections/actions also included included in the grid.
@@ -56,13 +60,15 @@ public interface LayoutService {
          * <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>serialized as XML</b></li>
          * </ul>
          */
+        // tag::refguide-1[]
         COMPLETE,
 
+        // end::refguide-1[]
         /**
          * Default, whereby missing properties/collections/actions are added to regions,
          * and unused/empty regions are removed/trimmed.
          * <p>
-         * It should be possible to remove any {@link MemberOrder} and {@link MemberGroupLayout} annotation but
+         * It should be possible to remove any {@link MemberOrder} annotation but
          * any property/collection/action layout annotations would need to be retained.
          * <ul>
          * <li>{@code @MemberGroupLayout}: <b>serialized as XML</b></li>
@@ -70,8 +76,10 @@ public interface LayoutService {
          * <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>ignored</b></li>
          * </ul>
          */
+        // tag::refguide-1[]
         NORMALIZED,
 
+        // end::refguide-1[]
         /**
          * As per {@link #NORMALIZED}, but with no properties/collections/actions.
          * <p>
@@ -83,25 +91,31 @@ public interface LayoutService {
          * <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>ignored</b></li>
          * </ul>
          */
+        // tag::refguide-1[]
         MINIMAL
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide[]
+    // end::refguide[]
     /**
      * Obtains the serialized XML form of the layout (grid) for the specified domain class.
      */
+    // tag::refguide[]
     String toXml(Class<?> domainClass, Style style);
 
+    // end::refguide[]
     /**
      * Obtains a zip file of the serialized XML of the layouts (grids) of all domain entities and view models.
      */
+    // tag::refguide[]
     byte[] toZip(final Style style);
 
+    // end::refguide[]
     /**
      * Obtains the serialized XML form of the menu bars layout ({@link MenuBarsService}).
      * @param type - either the current menubars (could be loaded from a file) or the fallback (obtained from metamodel facets)
      */
+    // tag::refguide[]
     String toMenuBarsXml(final MenuBarsService.Type type);
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/linking/DeepLinkService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/linking/DeepLinkService.java
index 963eafe..ef3ef9c 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/linking/DeepLinkService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/linking/DeepLinkService.java
@@ -33,10 +33,12 @@ import org.apache.isis.applib.annotation.Programmatic;
 // tag::refguide[]
 public interface DeepLinkService {
 
+    // end::refguide[]
     /**
      * Creates a URI that can be used to obtain a representation of the provided domain object in one of the
      * Isis viewers.
      */
+    // tag::refguide[]
     URI deepLinkFor(Object domainObject);
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsLoaderService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsLoaderService.java
index baadf11..5ca9688 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsLoaderService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsLoaderService.java
@@ -24,14 +24,18 @@ import org.apache.isis.applib.layout.menubars.bootstrap3.BS3MenuBars;
 // tag::refguide[]
 public interface MenuBarsLoaderService {
 
+    // end::refguide[]
     /**
      * Whether dynamic reloading of layouts is enabled.
      */
+    // tag::refguide[]
     boolean supportsReloading();
 
+    // end::refguide[]
     /**
      * Returns a new instance of a {@link BS3MenuBars}, else <tt>null</tt>.
      */
+    // tag::refguide[]
     BS3MenuBars menuBars();
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsService.java
index 940d762..10197af 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/menu/MenuBarsService.java
@@ -23,29 +23,34 @@ import org.apache.isis.applib.layout.menubars.MenuBars;
 // tag::refguide[]
 public interface MenuBarsService {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     enum Type {
 
+        // end::refguide-1[]
         /**
          * Either derived from annotations or as obtained elsewhere
          * (eg using the {@link MenuBarsLoaderService} if the
          * default implementation of this service is in use).
          */
+        // tag::refguide-1[]
         DEFAULT,
 
+        // end::refguide-1[]
         /**
          * As derived from annotations.
          */
+        // tag::refguide-1[]
         FALLBACK
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-1[]
+
 
     /**
      * Returns {@link #menuBars()} with a type of {@link Type#DEFAULT}.
      * @return
      */
+    // tag::refguide[]
     default MenuBars menuBars() {
         return menuBars(Type.DEFAULT);
     }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/message/MessageService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/message/MessageService.java
index dcfc3dc..b2e32d6 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/message/MessageService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/message/MessageService.java
@@ -25,6 +25,7 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
 // tag::refguide[]
 public interface MessageService {
 
+    // end::refguide[]
     /**
      * Make the specified message available to the user. Note this will probably
      * be displayed in transitory fashion, so is only suitable for useful but
@@ -34,8 +35,10 @@ public interface MessageService {
      * @see #warnUser(String)
      * @see #raiseError(String)
      */
+    // tag::refguide[]
     void informUser(String message);
 
+    // end::refguide[]
     /**
      * Make the specified message available to the user, translated (if possible) to user's locale.
      *
@@ -49,13 +52,17 @@ public interface MessageService {
      * @see #warnUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      * @see #raiseError(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      */
+    // tag::refguide[]
     String informUser(TranslatableString message, final Class<?> contextClass, final String contextMethod);
 
+    // end::refguide[]
     /**
      * Override of {@link MessageService#informUser(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
      */
+    // tag::refguide[]
     String informUser(TranslatableString message, final String translationContext);
 
+    // end::refguide[]
     /**
      * Warn the user about a situation with the specified message. The container
      * should guarantee to display this warning to the user, and will typically
@@ -65,8 +72,10 @@ public interface MessageService {
      * @see #raiseError(String)
      * @see #informUser(String)
      */
+    // tag::refguide[]
     void warnUser(String message);
 
+    // end::refguide[]
     /**
      * Warn the user about a situation with the specified message, translated (if possible) to user's locale.
      *
@@ -80,13 +89,17 @@ public interface MessageService {
      * @see #informUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      * @see #raiseError(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      */
+    // tag::refguide[]
     String warnUser(TranslatableString message, final Class<?> contextClass, final String contextMethod);
 
+    // end::refguide[]
     /**
      * Override of {@link MessageService#warnUser(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
      */
+    // tag::refguide[]
     String warnUser(TranslatableString message, final String translationContext);
 
+    // end::refguide[]
     /**
      * Notify the user of an application error with the specified message. Note
      * this will probably be displayed in an alarming fashion, so is only
@@ -96,8 +109,10 @@ public interface MessageService {
      * @see #warnUser(String)
      * @see #informUser(String)
      */
+    // tag::refguide[]
     void raiseError(String message);
 
+    // end::refguide[]
     /**
      * Notify the user of an application error with the specified message, translated (if possible) to user's locale.
      *
@@ -111,11 +126,14 @@ public interface MessageService {
      * @see #informUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      * @see #warnUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      */
+    // tag::refguide[]
     String raiseError(TranslatableString message, final Class<?> contextClass, final String contextMethod);
 
+    // end::refguide[]
     /**
      * Override of {@link MessageService#raiseError(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
      */
+    // tag::refguide[]
     String raiseError(TranslatableString message, final String translationContext);
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainMember.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainMember.java
index a696ab9..5a1f5a5 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainMember.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainMember.java
@@ -18,37 +18,31 @@
  */
 package org.apache.isis.applib.services.metamodel;
 
+// tag::refguide[]
 public interface DomainMember extends Comparable<DomainMember> {
 
     String getClassType();
 
     String getClassName();
-
     String getPackageName();
 
     String getType();
 
     String getMemberName();
-
     String getNumParams();
 
     boolean isContributed();
-
     String getContributedBy();
 
     boolean isMixedIn();
-
     String getMixin();
 
     String getHidden();
-
     String getDisabled();
+    String getValidate();
 
     String getChoices();
-
     String getAutoComplete();
-
     String getDefault();
-
-    String getValidate();
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainModel.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainModel.java
index 0ba797f..2a0127d 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainModel.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/DomainModel.java
@@ -20,8 +20,10 @@ package org.apache.isis.applib.services.metamodel;
 
 import java.util.List;
 
+// tag::refguide[]
 public interface DomainModel {
 
     List<DomainMember> getDomainMembers();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/MetaModelService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/MetaModelService.java
index 6d820b0..dd2ebf5 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/MetaModelService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metamodel/MetaModelService.java
@@ -43,18 +43,23 @@ import lombok.val;
 // tag::refguide[]
 public interface MetaModelService {
 
+    // end::refguide[]
     /**
      * Provides a reverse lookup of a domain class' object type, as defined by {@link DomainObject#objectType()} (or any other mechanism that corresponds to Isis' <code>ObjectSpecIdFacet</code>).
      */
+    // tag::refguide[]
     Class<?> fromObjectType(final String objectType);
 
+    // end::refguide[]
     /**
      * Provides a lookup of a domain class' object type, as defined by {@link DomainObject#objectType()} (or any other mechanism that corresponds to Isis' <code>ObjectSpecIdFacet</code>).
      */
+    // tag::refguide[]
     String toObjectType(final Class<?> domainType);
 
     void rebuild(final Class<?> domainType);
 
+    // end::refguide[]
     /**
      * Returns a list of representations of each of member of each domain class.
      *
@@ -67,6 +72,7 @@ public interface MetaModelService {
      * </p>
      *
      */
+    // tag::refguide[]
     DomainModel getDomainModel();
 
     BeanSort sortOf(Class<?> domainType, Mode mode);
@@ -75,22 +81,28 @@ public interface MetaModelService {
 
     CommandDtoProcessor commandDtoProcessorFor(String memberIdentifier);
 
-// end::refguide[]
-
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     enum Mode {
+
+        // end::refguide-1[]
         /**
          * If the {@link #sortOf(Class, Mode) sort of} object type is unknown, then throw an exception.
          */
+        // tag::refguide-1[]
         STRICT,
+
+        // end::refguide-1[]
         /**
          * If the {@link #sortOf(Class, Mode) sort of} object type is unknown, then return {@link Sort#UNKNOWN}.
          */
+        // tag::refguide-1[]
         RELAXED
+
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide-2[]
+    // tag::refguide-2[]
     class Config {
 
         private static final int IGNORE_NOOP_FACETS = 1;
@@ -182,10 +194,9 @@ public interface MetaModelService {
         }
 
     }
-// end::refguide-2[]
-
-// tag::refguide[]
+    // end::refguide-2[]
 
+    // tag::refguide[]
     MetamodelDto exportMetaModel(final Config config);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerService.java b/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerService.java
index 12bcc47..5cfc02a 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerService.java
@@ -42,16 +42,16 @@ import org.apache.isis.applib.services.bookmark.Bookmark;
 // tag::refguide[]
 public interface AuditerService {
 
-    boolean isEnabled();                                            // <1>
+    boolean isEnabled();                                            // <.>
 
     void audit(
-            final UUID interactionId, final int sequence,           // <2>
+            final UUID interactionId, final int sequence,           // <.>
             final String targetClassName,
-            final Bookmark target,                                  // <3>
+            final Bookmark target,                                  // <.>
             final String memberIdentifier,
-            final String propertyName,                              // <4>
-            final String preValue, final String postValue,          // <5>
-            final String user, final Timestamp timestamp);          // <6>
+            final String propertyName,                              // <.>
+            final String preValue, final String postValue,          // <.>
+            final String user, final Timestamp timestamp);          // <.>
 
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerServiceLogging.java b/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerServiceLogging.java
index adc9570..ebd7a23 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerServiceLogging.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/audit/AuditerServiceLogging.java
@@ -59,10 +59,12 @@ public class AuditerServiceLogging implements AuditerService {
             final String preValue, final String postValue,
             final String user, final Timestamp timestamp) {
 
-        String auditMessage =
-                interactionId + "," + sequence + ": " +
-                        target.toString() + " by " + user + ", " + propertyName + ": " + preValue + " -> " + postValue;
-        log.debug(auditMessage);
+        if(log.isDebugEnabled()) {
+            String auditMessage =
+                    interactionId + "," + sequence + ": " +
+                            target.toString() + " by " + user + ", " + propertyName + ": " + preValue + " -> " + postValue;
+            log.debug(auditMessage);
+        }
     }
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java
index 481db35..dc0e771 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/Bookmark.java
@@ -43,7 +43,7 @@ import lombok.val;
 // tag::refguide[]
 public class Bookmark implements Serializable {
 
-// end::refguide[]
+    // end::refguide[]
     private static final long serialVersionUID = 2L;
 
     protected static final String SEPARATOR = ":";
@@ -52,26 +52,28 @@ public class Bookmark implements Serializable {
      * corresponds directly to the object's specification-id
      * @see <code>RootOid</code>
      */
-// tag::refguide[]
+    // tag::refguide[]
     @NonNull  private final String objectType;
     @NonNull  private final String identifier;
-// end::refguide[]
+    // end::refguide[]
+
     @Nullable private final String hintId;
-// tag::refguide[]
+    // tag::refguide[]
 
     public static Bookmark of(String objectType, String identifier) {
         return new Bookmark(objectType, identifier, /*hintId*/ null);
     }
     // ...
 
-// end::refguide[]
+    // end::refguide[]
 
     /**
      * Round-trip with {@link #toString()} representation.
      */
-// tag::refguide[]
+    // tag::refguide[]
     public static Optional<Bookmark> parse(@Nullable String str) {
-// end::refguide[]
+    // end::refguide[]
+
         if(str==null) {
             return Optional.empty();
         }
@@ -85,10 +87,10 @@ public class Bookmark implements Serializable {
         }
         return Optional.empty();
 
-// tag::refguide[]
+        // tag::refguide[]
         // ...
     }
-// end::refguide[]
+    // end::refguide[]
 
     public OidDto toOidDto() {
         val oidDto = new OidDto();
@@ -122,6 +124,6 @@ public class Bookmark implements Serializable {
         return objectType + SEPARATOR + id;
     }
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_lookup.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_lookup.java
index de4cfca..846273b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_lookup.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_lookup.java
@@ -27,7 +27,6 @@ import org.apache.isis.applib.annotation.Contributed;
 import org.apache.isis.applib.annotation.Mixin;
 import org.apache.isis.applib.annotation.SemanticsOf;
 
-// tag::refguide[]
 @Mixin(method = "act")
 public class BookmarkHolder_lookup {
 
@@ -42,11 +41,11 @@ public class BookmarkHolder_lookup {
     @Action(
             domainEvent = ActionDomainEvent.class,
             semantics = SemanticsOf.SAFE
-            )
+    )
     @ActionLayout(
             contributed = Contributed.AS_ACTION,
             cssClassFa = "fa-bookmark"
-            )
+    )
     public Object act() {
         return bookmarkService.lookup(bookmarkHolder);
     }
@@ -54,4 +53,3 @@ public class BookmarkHolder_lookup {
     @Inject private BookmarkService bookmarkService;
 
 }
-// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_object.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_object.java
index 2565c2b..86b8528 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_object.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkHolder_object.java
@@ -27,7 +27,6 @@ import org.apache.isis.applib.annotation.Contributed;
 import org.apache.isis.applib.annotation.Mixin;
 import org.apache.isis.applib.annotation.SemanticsOf;
 
-// tag::refguide[]
 @Mixin(method = "prop")
 public class BookmarkHolder_object {
 
@@ -42,16 +41,14 @@ public class BookmarkHolder_object {
     @Action(
             semantics = SemanticsOf.SAFE,
             domainEvent = BookmarkHolder_object.ActionDomainEvent.class
-            )
+    )
     @ActionLayout(
             contributed = Contributed.AS_ASSOCIATION
-            )
+    )
     public Object prop() {
         return bookmarkService.lookup(bookmarkHolder);
     }
 
-
     @Inject private BookmarkService bookmarkService;
 
 }
-// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java
index ada7068..a0ef829 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmark/BookmarkService.java
@@ -20,6 +20,7 @@ package org.apache.isis.applib.services.bookmark;
 
 import javax.annotation.Nullable;
 
+import org.apache.isis.applib.services.metamodel.MetaModelService;
 import org.apache.isis.core.commons.internal.base._Casts;
 import org.apache.isis.core.commons.internal.exceptions._Exceptions;
 
@@ -34,21 +35,31 @@ import lombok.val;
 // tag::refguide[]
 public interface BookmarkService {
 
-// end::refguide[]
+    // end::refguide[]
     /**
-     * Given any {@link Bookmark} this service is able to reconstruct to originating domain object the {@link Bookmark}
-     * was created for.
+     * Returns the {@link Bookmark} for the given domain object.
+     *
      * <p>
-     * Note: Not every domain object is bookmark-able.
+     * <b>Note</b>: Not every domain object is bookmark-able: only entities, view models and services (NOT values or collections)
      * </p>
-     * @param domainObject
+     *
+     * @param domainObject - domain object (if any) to return a bookmark for
      * @return optionally a {@link Bookmark} representing given {@code domainObject}
      */
-// tag::refguide[]
+    // tag::refguide[]
     Bookmark bookmarkFor(@Nullable Object domainObject);
 
+    // end::refguide[]
+    /**
+     * As per {@link #bookmarkFor(Object)}, but requires that a non-null {@link Bookmark} is returned.
+     *
+     * @param domainObject - that can be bookmarked
+     * @return a (non-null) {@link Bookmark} for the provided domain object.
+     */
+    // tag::refguide[]
     default Bookmark bookmarkForElseThrow(Object domainObject) {
-// end::refguide[]
+        // end::refguide[]
+
         requires(domainObject, "domainObject");
         val bookmark = bookmarkFor(domainObject);
         if(bookmark!=null) {
@@ -56,21 +67,44 @@ public interface BookmarkService {
         }
         throw _Exceptions.illegalArgument(
                 "cannot create bookmark for type %s", domainObject.getClass().getName());
-// tag::refguide[]
+        // tag::refguide[]
         // ...
     }
 
+    // end::refguide[]
+    /**
+     * Utility method that creates a {@link Bookmark} from the constituent parts.
+     *
+     * @return - {@link Bookmark} for provided class and identifier
+     */
+    // tag::refguide[]
     Bookmark bookmarkFor(Class<?> cls, String identifier);
 
+    // end::refguide[]
+    /**
+     * @see #lookup(Bookmark)
+     *
+     * @param bookmarkHolder - from which the {@link Bookmark} is obtained
+     * @return - corresponding domain object
+     */
+    // tag::refguide[]
     Object lookup(BookmarkHolder bookmarkHolder);
 
+    // end::refguide[]
+    /**
+     * Reciprocal of {@link #bookmarkFor(Object)}
+     *
+     * @param bookmark - representing a domain object
+     * @return - the corresponding domain object
+     */
+    // tag::refguide[]
     Object lookup(Bookmark bookmark);
 
-// end::refguide[]
+    // end::refguide[]
     /**
      * As {@link #lookup(Bookmark)}, but down-casting to the specified type.
      */
-// tag::refguide[]
+    // tag::refguide[]
     default <T> T lookup(Bookmark bookmark, Class<T> cls) {
         return cls.cast(lookup(bookmark));
     }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/bookmarkui/BookmarkUiService.java b/api/applib/src/main/java/org/apache/isis/applib/services/bookmarkui/BookmarkUiService.java
index e21431b..d94ec32 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/bookmarkui/BookmarkUiService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/bookmarkui/BookmarkUiService.java
@@ -23,6 +23,6 @@ import org.apache.isis.applib.annotation.Programmatic;
 
 // tag::refguide[]
 public interface BookmarkUiService {
-    void clear();                   // <1>
+    void clear();                       // <.>
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java
index 1230b7b..f030cb6 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/Command.java
@@ -105,9 +105,7 @@ public interface Command extends HasUniqueId {
     // end::refguide[]
 
     /**
-     *
      * The date/time at which this command was created.
-     *
      */
     // tag::refguide[]
     Timestamp getTimestamp();                   // <.>
@@ -118,13 +116,13 @@ public interface Command extends HasUniqueId {
      *
      * <p>
      * Will only be populated if a {@link BookmarkService} has been configured.
+     * </p>
      */
     // tag::refguide[]
     Bookmark getTarget();                       // <.>
     // end::refguide[]
 
     /**
-     *
      * Holds a string representation of the invoked action, or the edited property, equivalent to
      * {@link Identifier#toClassAndNameIdentityString()}.
      */
@@ -133,7 +131,6 @@ public interface Command extends HasUniqueId {
     // end::refguide[]
 
     /**
-     *
      * A human-friendly description of the class of the target object.
      */
     // tag::refguide[]
@@ -141,19 +138,13 @@ public interface Command extends HasUniqueId {
     // end::refguide[]
 
     /**
-     *
      * The human-friendly name of the action invoked/property edited on the target object.
-     *
-     * <p>
-     *     NB: in earlier versions, if the command represented an edit of a property, then it held the special value &quot;{@value ACTION_IDENTIFIER_FOR_EDIT}&quot;.  This is NO LONGER the case; it simply holds the member.
-     * </p>
      */
     // tag::refguide[]
     String getTargetAction();                   // <.>
     // end::refguide[]
 
     /**
-     *
      * A human-friendly description of the arguments with which the action was invoked.
      */
     // tag::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java
index 9716944..2f7b4d0 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandContext.java
@@ -72,7 +72,7 @@ public class CommandContext {
     @Getter
     private Command command;
 
-// end::refguide[]
+    // end::refguide[]
     /**
      * <b>NOT API</b>: intended to be called only by the framework.
      */
@@ -85,7 +85,6 @@ public class CommandContext {
                 .map(Command::getExecutor);
     }
 
-
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandExecutorService.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandExecutorService.java
index cfffa0a..917a4e5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandExecutorService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/CommandExecutorService.java
@@ -21,16 +21,25 @@ package org.apache.isis.applib.services.command;
 // tag::refguide[]
 public interface CommandExecutorService {
 
+    // end::refguide[]
+    // tag::refguide-2[]
     enum SudoPolicy {
+
+        // end::refguide-2[]
         /**
          * For example, regular background commands.
          */
+        // tag::refguide-2[]
         NO_SWITCH,
+
+        // end::refguide-2[]
         /**
          * For example, replayable commands.
          */
+        // tag::refguide-2[]
         SWITCH,
     }
+    // end::refguide-2[]
 
     /**
      * Executes the specified command.
@@ -39,7 +48,11 @@ public interface CommandExecutorService {
      * @param commandWithDto
      * @return - any exception raised by the command.
      */
-    void executeCommand(SudoPolicy sudoPolicy, CommandWithDto commandWithDto);
+    // tag::refguide[]
+    void executeCommand(
+            SudoPolicy sudoPolicy,              // <.>
+            CommandWithDto commandWithDto       // <.>
+    );
 
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java b/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java
index 8afa756..eb3abce 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/command/spi/CommandService.java
@@ -26,7 +26,7 @@ import org.apache.isis.applib.services.command.Command;
 // tag::refguide[]
 public interface CommandService {
 
-// end::refguide[]
+    // end::refguide[]
     /**
      * Simply instantiates the appropriate instance of the {@link Command}.
      *
@@ -35,17 +35,17 @@ public interface CommandService {
      * {@link Command#getTimestamp()}, {@link Command#getUser()} and {@link Command#getUniqueId()}).
      * </p>
      */
-// tag::refguide[]
+    // tag::refguide[]
     Command create();                               // <.>
-// end::refguide[]
+    // end::refguide[]
 
     /**
      * Hint for this implementation to eagerly persist the {@link Command}s if possible; influences the behaviour
      * of actions annotated to execute in the {@link org.apache.isis.applib.annotation.CommandExecuteIn#BACKGROUND}.
      */
-// tag::refguide[]
+    // tag::refguide[]
     boolean persistIfPossible(Command command);     // <.>
-// end::refguide[]
+    // end::refguide[]
 
     /**
      * &quot;Complete&quot; the command, typically meaning to indicate that the command is completed, and to
@@ -59,7 +59,7 @@ public interface CommandService {
      *     The framework will automatically have set the {@link Command#getCompletedAt()} property.
      * </p>
      */
-// tag::refguide[]
+    // tag::refguide[]
     void complete(final Command command);           // <.>
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationViewService.java b/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationViewService.java
index bc71130..9627c0f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationViewService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/confview/ConfigurationViewService.java
@@ -26,10 +26,12 @@ import org.apache.isis.applib.annotation.Programmatic;
 // tag::refguide[]
 public interface ConfigurationViewService {
 
+    // end::refguide[]
     /**
      * Returns all properties, each as an instance of {@link ConfigurationProperty} (a view model).
      * Mask sensitive values if required.
      */
+    // tag::refguide[]
     Set<ConfigurationProperty> allProperties();
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/conmap/ContentMappingService.java b/api/applib/src/main/java/org/apache/isis/applib/services/conmap/ContentMappingService.java
index c95ad15..369349e 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/conmap/ContentMappingService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/conmap/ContentMappingService.java
@@ -30,15 +30,18 @@ import org.apache.isis.core.commons.internal.base._NullSafe;
 // tag::refguide[]
 public interface ContentMappingService {
 
+    // end::refguide[]
     /**
      * Typically for mapping from a domain object to a DTO.
      */
+    // tag::refguide[]
     Object map(Object object, final List<MediaType> acceptableMediaTypes);
 
-// end::refguide[]
+    // end::refguide[]
     /**
      * Convenience utilities for implementations of {@link ContentMappingService}.
      */
+    // tag::refguide-2[]
     public static class Util {
 
         public static String determineDomainType(final List<MediaType> acceptableMediaTypes) {
@@ -64,7 +67,8 @@ public interface ContentMappingService {
             return clazz.getName().equals(domainType);
         }
     }
+    // end::refguide-2[]
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/email/EmailService.java b/api/applib/src/main/java/org/apache/isis/applib/services/email/EmailService.java
index be7f54d..e5960e7 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/email/EmailService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/email/EmailService.java
@@ -37,20 +37,16 @@ import org.apache.isis.applib.annotation.Programmatic;
 // tag::refguide[]
 public interface EmailService extends Serializable {
 
-    /**
-     * Always called by the framework, and allows the implementation to read configuration properties and initialize itself
-     */
     @PostConstruct
     public void init() ;
 
-    /**
-     * Main API to send email and optional attachments.
-     */
     boolean send(List<String> to, List<String> cc, List<String> bcc, String subject, String body, DataSource... attachments);
 
+    // end::refguide[]
     /**
      * Whether this service has been configured and thus available for use.
      */
+    // tag::refguide[]
     boolean isConfigured();
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/error/Ticket.java b/api/applib/src/main/java/org/apache/isis/applib/services/error/Ticket.java
index 0d55843..dca850f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/error/Ticket.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/error/Ticket.java
@@ -34,10 +34,13 @@ import java.io.Serializable;
 // tag::refguide[]
 public interface Ticket extends Serializable {
 
+    // end::refguide[]
+    // tag::refguide-2[]
     enum StackTracePolicy {
         SHOW,
         HIDE
     }
+    // end::refguide-2[]
 
     /**
      * A unique identifier that the end-user can use to track any follow-up from this error.
@@ -47,8 +50,10 @@ public interface Ticket extends Serializable {
      *     which case the {@link #getReference() reference} would be the JIRA issue number <tt>XXX-1234</tt>.
      * </p>
      */
+    // tag::refguide[]
     String getReference();
 
+    // end::refguide[]
     /**
      * Message to display to the user.
      *
@@ -56,8 +61,10 @@ public interface Ticket extends Serializable {
      *     Typically this message should be short, one line long.
      * </p>
      */
+    // tag::refguide[]
     String getUserMessage();
 
+    // end::refguide[]
     /**
      * Optional additional details to show to the end-user.
      *
@@ -66,8 +73,10 @@ public interface Ticket extends Serializable {
      *     details on contacting the help desk if the issue is severe and requires immediate attention.
      * </p>
      */
+    // tag::refguide[]
     String getDetails();
 
+    // end::refguide[]
     /**
      * Whether the stack trace for the exception should be displayed or be hidden.
      *
@@ -76,11 +85,14 @@ public interface Ticket extends Serializable {
      *     the support team, meaning there's no need to expose this info to the end-user.
      * </p>
      */
+    // tag::refguide[]
     StackTracePolicy getStackTracePolicy();
 
+    // end::refguide[]
     /**
      * Returns a Html representation of this ticket.
      */
+    // tag::refguide[]
     String getMarkup();
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizer.java b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizer.java
index c5ca151..8c75c23 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizer.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizer.java
@@ -61,63 +61,86 @@ import lombok.val;
 // tag::refguide[]
 public interface ExceptionRecognizer {
 
+    // end::refguide[]
     /**
      * (Attempt to) recognize the exception and return a user-friendly
-     * message to render instead. 
+     * message to render instead.
      *
-     * @return optionally a 
-     * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition recognition} object, 
-     * that describes both the 
-     * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category category} 
-     * and reason that will be included with the user-friendly message. 
+     * @return optionally a
+     * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Recognition recognition} object,
+     * that describes both the
+     * {@link org.apache.isis.applib.services.exceprecog.ExceptionRecognizer.Category category}
+     * and reason that will be included with the user-friendly message.
      */
+    // tag::refguide[]
     Optional<Recognition> recognize(Throwable ex);
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     @RequiredArgsConstructor
     enum Category {
+
+        // end::refguide-1[]
         /**
          * A violation of some declarative constraint (eg uniqueness or referential integrity) was detected.
          */
+        // tag::refguide-1[]
         CONSTRAINT_VIOLATION("violation of some declarative constraint"),
+
+        // end::refguide-1[]
         /**
          * The object to be acted upon cannot be found (404)
          */
+        // tag::refguide-1[]
         NOT_FOUND("object not found"),
+
+        // end::refguide-1[]
         /**
          * A concurrency exception, in other words some other user has changed this object.
          */
+        // tag::refguide-1[]
         CONCURRENCY("concurrent modification"),
+
+        // end::refguide-1[]
         /**
          * Recognized, but for some other reason... 40x error
          */
+        // tag::refguide-1[]
         CLIENT_ERROR("client side error"),
+
+        // end::refguide-1[]
         /**
          * 50x error
          */
+        // tag::refguide-1[]
         SERVER_ERROR("server side error"),
+
+        // end::refguide-1[]
         /**
          * Recognized, but uncategorized (typically: a recognizer of the original ExceptionRecognizer API).
          */
+        // tag::refguide-1[]
         OTHER("other")
         ;
-        
+
         @Getter
         private final String friendlyName;
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide-2[]
+    // tag::refguide-2[]
     @Value
     class Recognition {
 
+        // end::refguide-2[]
         /**
          * @return optionally a recognition of the specified type, based on a whether given reason is non-null
          */
+        // tag::refguide-2[]
         public static Optional<Recognition> of(
                 @Nullable final Category category,
                 @Nullable final String reason) {
+            // end::refguide-2[]
 
             if(reason==null) {
                 return Optional.empty();
@@ -125,27 +148,34 @@ public interface ExceptionRecognizer {
 
             val nonNullCategory = category!=null? category: Category.OTHER;
             return Optional.of(new Recognition(nonNullCategory, reason));
+            // tag::refguide-2[]
+            // ...
         }
 
         @NonNull private final Category category;
         @NonNull private final String reason;
 
         public String toMessage(@Nullable TranslationService translationService) {
-            
+            // end::refguide-2[]
+
             val categoryLiteral = translationService!=null
                     ? translationService.translate(
                             ExceptionRecognizer.Category.class.getName(), getCategory().getFriendlyName())
                             : getCategory().getFriendlyName();
-                            
+
             val reasonLiteral = translationService!=null
                     ? translationService.translate(
                             ExceptionRecognizer.Recognition.class.getName(), getReason())
                             : getReason();
-            
+
             return String.format("[%s]: %s", categoryLiteral, reasonLiteral);
+            // tag::refguide-2[]
+            // ...
         }
+        // end::refguide-2[]
     }
-// end::refguide-2[]
-// tag::refguide[]
+    // end::refguide-2[]
+
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizerService.java b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizerService.java
index 64e0edd..2c8043b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizerService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/ExceptionRecognizerService.java
@@ -31,31 +31,38 @@ import org.apache.isis.core.commons.collections.Can;
 // tag::refguide[]
 public interface ExceptionRecognizerService {
 
+    // end::refguide[]
     /**
-     * 
-     * @return all ExceptionRecognizer implementations as discovered by the IoC container, 
-     * honoring order of precedence. 
+     *
+     * @return all ExceptionRecognizer implementations as discovered by the IoC container,
+     * honoring order of precedence.
      */
+    // tag::refguide[]
     Can<ExceptionRecognizer> getExceptionRecognizers();
 
+    // end::refguide[]
     /**
      * Takes into consideration ExceptionRecognizers as given by {@link #getExceptionRecognizers()}.
      *
-     * @param ex
-     * @return optionally a recognition object, that describes both the category and reason, 
-     * that will be included with the user-friendly message. 
+     * @param ex - exception to be recognized
+     * @return optionally a recognition object, that describes both the category and reason,
+     * that will be included with the user-friendly message.
      */
+    // tag::refguide[]
     default Optional<Recognition> recognize(Exception ex) {
         return recognizeFromSelected(getExceptionRecognizers(), ex);
     }
 
+    // end::refguide[]
     /**
      * Takes into consideration ExceptionRecognizers as given by {@code recognizers}.
-     * @param recognizers
-     * @param ex
-     * @return optionally a recognition object, that describes both the category and reason, 
-     * that will be included with the user-friendly message. 
+     *
+     * @param recognizers - one or more recognizers to attempt to recognize the exceptoin
+     * @param ex - the exception to be recognized
+     * @return optionally a recognition object, that describes both the category and reason,
+     * that will be included with the user-friendly message.
      */
+    // tag::refguide[]
     Optional<Recognition> recognizeFromSelected(Can<ExceptionRecognizer> recognizers, Exception ex);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/TranslatableException.java b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/TranslatableException.java
index 58e27e4..1e70cbc 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/TranslatableException.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/exceprecog/TranslatableException.java
@@ -33,6 +33,7 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
 // tag::refguide[]
 public interface TranslatableException {
 
+    // end::refguide[]
     /**
      * In the spirit of {@link Exception#getLocalizedMessage()}, but using {@link org.apache.isis.applib.services.i18n.TranslatableString} instead.
      *
@@ -43,12 +44,15 @@ public interface TranslatableException {
      *     accept a {@link org.apache.isis.applib.services.i18n.TranslatableString}, but can be left as null for any existing code.
      * </p>
      */
+    // tag::refguide[]
     TranslatableString getTranslatableMessage();
 
+    // end::refguide[]
     /**
      * The context to use when translating the {@link #getTranslatableMessage() translatable message},
      * as ultimately passed through to {@link org.apache.isis.applib.services.i18n.TranslationService#translate(String, String)}.
      */
+    // tag::refguide[]
     String getTranslationContext();
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java b/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java
index b03a26e..e09fdf6 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/factory/FactoryService.java
@@ -23,17 +23,19 @@ import java.util.NoSuchElementException;
 
 import javax.annotation.Nullable;
 
+import org.apache.isis.applib.services.repository.RepositoryService;
 import org.apache.isis.core.commons.exceptions.IsisException;
 
 // tag::refguide[]
 public interface FactoryService {
 
+    // end::refguide[]
     /**
      * General purpose factory method, to automatically get or create an instance of
      * {@code requiredType}.
      *
      * <p>
-     * Maps onto one of the specialized factory methods {@link #get(Class)} or {@link #create(Class)} 
+     * Maps onto one of the specialized factory methods {@link #get(Class)} or {@link #create(Class)}
      * based on the type's meta-data.
      * </p>
      *
@@ -47,40 +49,48 @@ public interface FactoryService {
      * @since 2.0
      *
      */
+    // tag::refguide[]
     <T> T getOrCreate(Class<T> requiredType);
 
+    // end::refguide[]
     /**
-     * Gets an instance (possibly shared or independent) of the specified {@code requiredType}, 
-     * with injection points resolved 
+     * Gets an instance (possibly shared or independent) of the specified {@code requiredType},
+     * with injection points resolved
      * and any life-cycle callback processed.
-     * 
+     *
      * @param <T>
      * @param requiredType - only applicable to IoC container managed types
      * @return (non-null), an instance of {@code requiredType}, if available and unique
      * (i.e. not multiple candidates found with none marked as primary)
-     * 
+     *
      * @throws NoSuchElementException if result is empty
      * @throws IsisException if instance creation failed
-     * 
+     *
      * @apiNote does not force the requiredType to be added to the meta-model
      * @since 2.0
      */
+    // tag::refguide[]
     <T> T get(Class<T> requiredType);
 
+    // end::refguide[]
     /**
      * Creates a new detached entity instance, with injection points resolved
      * and defaults applied.
+     *
      * @param <T>
      * @param domainClass - only applicable to entity types
      * @return
-     * @throws IllegalArgumentException if domainClass is not an entity type  
+     * @throws IllegalArgumentException if domainClass is not an entity type
      * @apiNote forces the domainClass to be added to the meta-model if not already
      * @since 2.0
      */
+    // tag::refguide[]
     <T> T detachedEntity(Class<T> domainClass);
 
+    // end::refguide[]
     /**
      * Creates a new Mixin instance, with injection points resolved.
+     *
      * @param <T>
      * @param mixinClass
      * @param mixedIn
@@ -88,44 +98,52 @@ public interface FactoryService {
      * @throws IllegalArgumentException if mixinClass is not a mixin type
      * @apiNote forces the mixinClass to be added to the meta-model if not already
      */
+    // tag::refguide[]
     <T> T mixin(Class<T> mixinClass, Object mixedIn);
 
+    // end::refguide[]
     /**
-     * Creates a new ViewModel instance, with injection points resolved, 
-     * and initialized according to the given {@code mementoStr} 
+     * Creates a new ViewModel instance, with injection points resolved,
+     * and initialized according to the given {@code mementoStr}
+     *
      * @param viewModelClass
      * @param mementoStr - ignored if {@code null}
      * @throws IllegalArgumentException if viewModelClass is not a viewmodel type
      * @apiNote forces the viewModelClass to be added to the meta-model if not already
      * @since 2.0
      */
+    // tag::refguide[]
     <T> T viewModel(Class<T> viewModelClass, @Nullable String mementoStr);
 
+    // end::refguide[]
     /**
-     * Creates a new ViewModel instance, 
+     * Creates a new ViewModel instance,
      * with injection points resolved
-     * and defaults applied. 
+     * and defaults applied.
      * @param viewModelClass
      * @throws IllegalArgumentException if viewModelClass is not a viewmodel type
      * @apiNote forces the viewModelClass to be added to the meta-model if not already
      * @since 2.0
      */
+    // tag::refguide[]
     default <T> T viewModel(Class<T> viewModelClass) {
         return viewModel(viewModelClass, /*mementoStr*/null);
     }
 
+    // end::refguide[]
     /**
-     * Creates a new instance of the specified class, 
+     * Creates a new instance of the specified class,
      * with injection points resolved
      * and defaults applied.
      * @param domainClass - not applicable to IoC container managed types
-     * @throws IllegalArgumentException if domainClass is an IoC container managed type, 
+     * @throws IllegalArgumentException if domainClass is an IoC container managed type,
      *      or not recognized by the meta-model
      * @apiNote forces the domainClass to be added to the meta-model if not already
      * @since 2.0
      */
+    // tag::refguide[]
     <T> T create(Class<T> domainClass);
-// end::refguide[]
+    // end::refguide[]
 
     // -- DEPRECATIONS
 
@@ -156,8 +174,8 @@ public interface FactoryService {
      * alternatively just <i>new()</i> up the object rather than call this
      * method.
      * </p>
-     * @deprecated with semantic changes since 2.0 previous behavior is no longer guaranteed, 
-     * instead consider use of @{@link #detachedEntity(Class)} or {@link #getOrCreate(Class)} 
+     * @deprecated with semantic changes since 2.0 previous behavior is no longer guaranteed,
+     * instead consider use of @{@link #detachedEntity(Class)} or {@link #getOrCreate(Class)}
      * if applicable
      */
     @Deprecated
@@ -165,6 +183,6 @@ public interface FactoryService {
         return getOrCreate(domainClass);
     }
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridLoaderService.java b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridLoaderService.java
index 7828441..202eb65 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridLoaderService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridLoaderService.java
@@ -24,31 +24,41 @@ import org.apache.isis.applib.layout.grid.Grid;
 // tag::refguide[]
 public interface GridLoaderService {
 
+    // end::refguide[]
     /**
      * Whether dynamic reloading of layouts is enabled.
      */
+    // tag::refguide[]
     boolean supportsReloading();
 
+    // end::refguide[]
     /**
      * To support metamodel invalidation/rebuilding of spec.
      */
+    // tag::refguide[]
     void remove(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Whether any persisted layout metadata (eg a <code>.layout.xml</code> file) exists for this domain class.
      */
+    // tag::refguide[]
     boolean existsFor(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Returns a new instance of a {@link Grid} for the specified domain class, eg from a
      * <code>layout.xml</code> file, else <code>null</code>.
      */
+    // tag::refguide[]
     Grid load(final Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Returns a new instance of a {@link Grid} for the specified domain class, eg from a
      * <code>layout.xml</code> file, else <code>null</code>.
      */
+    // tag::refguide[]
     Grid load(final Class<?> domainClass, String layout);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridService.java b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridService.java
index bdfa20a..f9db3c5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridService.java
@@ -29,32 +29,43 @@ import org.apache.isis.applib.layout.grid.Grid;
 // tag::refguide[]
 public interface GridService {
 
+    // end::refguide[]
     /**
      * Whether dynamic reloading of layouts is enabled.
      */
+    // tag::refguide[]
     boolean supportsReloading();
 
+    // end::refguide[]
     /**
      * To support metamodel invalidation/rebuilding of spec.
      */
+    // tag::refguide[]
     void remove(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Whether any persisted layout metadata (eg a <code>.layout.xml</code> file) exists for this domain class.
      */
+    // tag::refguide[]
     boolean existsFor(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Returns a new instance of a {@link Grid} for the specified domain class, eg from a
      * <code>layout.xml</code> file, else <code>null</code>.
      */
+    // tag::refguide[]
     Grid load(final Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Returns a default grid; eg where none can be loaded using {@link #load(Class)}.
      */
+    // tag::refguide[]
     Grid defaultGridFor(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Returns a normalized grid for the domain class obtained previously using {@link #load(Class)}.
      *
@@ -69,8 +80,10 @@ public interface GridService {
      *     <code>layout.xml</code> file takes precedence over any annotations.
      * </p>
      */
+    // tag::refguide[]
     Grid normalize(final Grid grid);
 
+    // end::refguide[]
     /**
      * Modifies the provided {@link Grid} with additional metadata, broadly speaking corresponding to the
      * {@link DomainObjectLayout}, {@link ActionLayout}, {@link PropertyLayout} and {@link CollectionLayout}.
@@ -81,8 +94,10 @@ public interface GridService {
      *     to be required in the domain class itself.
      * </p>
      */
+    // tag::refguide[]
     Grid complete(Grid grid);
 
+    // end::refguide[]
     /**
      * Modifies the provided {@link Grid}, removing all metadata except the basic grid structure.
      *
@@ -95,12 +110,15 @@ public interface GridService {
      * @param grid
      * @return
      */
+    // tag::refguide[]
     Grid minimal(Grid grid);
 
+    // end::refguide[]
     /**
      * Returns a new instance of a {@link Grid} for the specified domain class, eg from a
      * <code>[domainClass].layout.[layout].xml</code> file, else <code>null</code>.
      */
+    // tag::refguide[]
     Grid load(Class<?> domainClass, String layout);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridSystemService.java b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridSystemService.java
index bdeab5d..5a2c289 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridSystemService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/grid/GridSystemService.java
@@ -27,9 +27,11 @@ import org.apache.isis.applib.layout.grid.Grid;
 // tag::refguide[]
 public interface GridSystemService<G extends Grid> {
 
+    // end::refguide[]
     /**
      * Which grid (implementation) is defined by this service.
      */
+    // tag::refguide[]
     Class<G> gridImplementation();
 
     String tns();
@@ -38,10 +40,12 @@ public interface GridSystemService<G extends Grid> {
 
     G defaultGrid(Class<?> domainClass);
 
+    // end::refguide[]
     /**
      * Validate the grid, derive any missing object members, and overwrite any facets in the metamodel based on the
      * layout.
      */
+    // tag::refguide[]
     void normalize(G grid, Class<?> domainClass);
 
     void complete(G grid, Class<?> domainClass);
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/health/Health.java b/api/applib/src/main/java/org/apache/isis/applib/services/health/Health.java
index 82c7dda..c908630 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/health/Health.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/health/Health.java
@@ -21,6 +21,7 @@ package org.apache.isis.applib.services.health;
 import lombok.AllArgsConstructor;
 import lombok.Getter;
 
+// tag::refguide[]
 @AllArgsConstructor
 public class Health {
 
@@ -41,3 +42,4 @@ public class Health {
 
     public boolean getResult() { return message == null; }
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/hint/HintStore.java b/api/applib/src/main/java/org/apache/isis/applib/services/hint/HintStore.java
index da2d21e..8572827 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/hint/HintStore.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/hint/HintStore.java
@@ -26,13 +26,13 @@ import org.apache.isis.applib.services.bookmark.Bookmark;
 // tag::refguide[]
 public interface HintStore {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     interface HintIdProvider {
         String hintId();
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-1[]
+    // tag::refguide[]
 
     String get(final Bookmark bookmark, String hintKey);
 
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/homepage/HomePageResolverService.java b/api/applib/src/main/java/org/apache/isis/applib/services/homepage/HomePageResolverService.java
index 263ae0e..a4a7f6b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/homepage/HomePageResolverService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/homepage/HomePageResolverService.java
@@ -22,6 +22,7 @@ import org.apache.isis.applib.annotation.HomePage;
 
 /**
  * Returns a view model annotated with {@link HomePage}.
+ *
  * @since 2.0
  */
 // tag::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java b/api/applib/src/main/java/org/apache/isis/applib/services/homepage/package-info.java
similarity index 77%
copy from api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
copy to api/applib/src/main/java/org/apache/isis/applib/services/homepage/package-info.java
index 0ba797f..2bb38af 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/homepage/package-info.java
@@ -16,12 +16,9 @@
  *  specific language governing permissions and limitations
  *  under the License.
  */
-package org.apache.isis.applib.services.metamodel;
 
-import java.util.List;
-
-public interface DomainModel {
-
-    List<DomainMember> getDomainMembers();
-
-}
+/**
+ * The {@link org.apache.isis.applib.services.homepage.HomePageResolverService} returns the view model, if any
+ * annotated with {@link org.apache.isis.applib.annotation.HomePage}.
+ */
+package org.apache.isis.applib.services.homepage;
\ No newline at end of file
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java b/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java
index 8f8f1f9..30de466 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslatableString.java
@@ -28,9 +28,11 @@ import org.apache.isis.applib.annotation.Programmatic;
 import org.apache.isis.applib.annotation.Value;
 import org.apache.isis.core.commons.internal.collections._Lists;
 
+// tag::refguide[]
 @Value
 public final class TranslatableString {
 
+    // end::refguide[]
     // -- tr, trn (factory methods); constructor
 
     /**
@@ -39,15 +41,22 @@ public final class TranslatableString {
      * @param pattern - pattern for all (singular and plural) form, with <code>${xxx}</code> placeholders
      * @param paramArgs - parameter/argument pairs (string and object, string and object, ...)
      */
+    // tag::refguide[]
     public static TranslatableString tr(
             final String pattern,
             final Object... paramArgs) {
+        // end::refguide[]
+
         if(pattern == null) {
             return null;
         }
         return new TranslatableString(Type.TR, pattern, null, 1, asMap(paramArgs));
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * A translatable string with different patterns for singular and plural forms, selected automatically by the number
      *
@@ -56,14 +65,20 @@ public final class TranslatableString {
      * @param number - whether to use singular or plural form when rendering
      * @param paramArgs - parameter/argument pairs (string and object, string and object, ...)
      */
+    // tag::refguide[]
     public static TranslatableString trn(
             final String singularPattern,
             final String pluralPattern,
             final int number,
             final Object... paramArgs) {
+
         return new TranslatableString(Type.TRN, singularPattern, pluralPattern, number, asMap(paramArgs));
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * Converts a list of objects [a, 1, b, 2] into a map {a -> 1; b -> 2}
      */
@@ -181,8 +196,9 @@ public final class TranslatableString {
      * @param context
      * @return
      */
-    @Programmatic
+    // tag::refguide[]
     public String translate(final TranslationService translationService, final String context) {
+
         final String translatedText =
                 !isPluralForm()
                 ? translationService.translate(context, getSingularText())
@@ -190,6 +206,7 @@ public final class TranslatableString {
                 return translated(translatedText);
     }
 
+    // end::refguide[]
     /**
      * The text to be translated; depends on whether {@link #isPluralForm()} and whether to be translated.
      *
@@ -203,10 +220,11 @@ public final class TranslatableString {
      *     {@link Exception#getMessage() message} when only a translatable message has been provided.
      * </p>
      */
-    @Programmatic
+    // tag::refguide[]
     public String getPattern() {
         return !isPluralForm() || number == 1 ? getSingularText() : getPluralText();
     }
+    // end::refguide[]
 
     String translated(final String translatedText) {
         return format(translatedText, argumentsByParameterName);
@@ -269,6 +287,6 @@ public final class TranslatableString {
         return type.toString(this);
     }
 
-
-
+    // tag::refguide[]
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslationService.java b/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslationService.java
index 17e791e..5f55e2f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslationService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/i18n/TranslationService.java
@@ -24,6 +24,7 @@ import java.util.function.Predicate;
 // tag::refguide[]
 public interface TranslationService {
 
+    // end::refguide[]
     /**
      * Return a translation of the text, in the locale of the &quot;current user&quot;.
      *
@@ -35,8 +36,10 @@ public interface TranslationService {
      * @param text
      * @return
      */
+    // tag::refguide[]
     String translate(final String context, final String text);
 
+    // end::refguide[]
     /**
      * Return a translation of either the singular or the plural text, dependent on the <tt>num</tt> parameter,
      * in the locale of the &quot;current user&quot;.
@@ -51,23 +54,48 @@ public interface TranslationService {
      * @param num - whether to return the translation of the singular (if =1) or of the plural (if != 1)
      * @return
      */
+    // tag::refguide[]
     String translate(final String context, final String singularText, final String pluralText, int num);
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     enum Mode {
-        DISABLED(configValue->configValue != null &&
-                ("disable".equalsIgnoreCase(configValue) ||
-                        "disabled".equalsIgnoreCase(configValue))),
+
+        DISABLED (
+            // end::refguide-1[]
+                configValue->
+                    ("disable".equalsIgnoreCase(configValue) ||
+                     "disabled".equalsIgnoreCase(configValue))
+            // tag::refguide-1[]
+            // ...
+        ),
 
         // synonym, needs to be defined, such that config beans (since 2.0) do work
-        DISABLE(configValue->false),
+        DISABLE(
+            // end::refguide-1[]
+                configValue->false
+            // tag::refguide-1[]
+            // ...
+        ),
+
+        READ(
+            // end::refguide-1[]
+                configValue->
+                    ("read".equalsIgnoreCase(configValue) ||
+                     "reader".equalsIgnoreCase(configValue))
+            // tag::refguide-1[]
+            // ...
+        ),
 
-        READ(configValue->configValue != null &&
-        ("read".equalsIgnoreCase(configValue) ||
-                "reader".equalsIgnoreCase(configValue))),
-        // default
-        WRITE(configValue->!READ.matches(configValue) && !DISABLED.matches(configValue));
+        WRITE(
+            // end::refguide-1[]
+                configValue ->
+                    !READ.matches(configValue) &&
+                    !DISABLED.matches(configValue)
+            // tag::refguide-1[]
+            // ...
+        );
+        // end::refguide-1[]
 
         // -- handle values from configuration
 
@@ -90,9 +118,10 @@ public interface TranslationService {
         public boolean isDisabled() {
             return this == DISABLED || this == DISABLE;
         }
+
+        // tag::refguide-1[]
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-1[]
 
     /**
      * Whether this implementation is operating in read or in write mode.
@@ -112,6 +141,8 @@ public interface TranslationService {
      *     such that all pathways are exercised..
      * </p>
      */
+    // tag::refguide[]
     Mode getMode();
+
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java b/api/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java
index 65a2112..c65f26f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/iactn/Interaction.java
@@ -84,11 +84,12 @@ import lombok.extern.log4j.Log4j2;
 @Log4j2
 public class Interaction implements HasUniqueId {
 
-
     @Getter @Setter
     private UUID uniqueId;
+    // end::refguide[]
 
     private final List<Execution<?,?>> executionGraphs = _Lists.newArrayList();
+
     /**
      * Returns a (list of) {@link Execution}s in the order that they were pushed.  Generally there will be just one entry in this list, but additional entries may arise from the use of mixins/contributions when re-rendering a modified object.
      *
@@ -105,23 +106,33 @@ public class Interaction implements HasUniqueId {
      *  {@link #execute(MemberExecutor, ActionInvocation, ClockService, MetricsService)} for us, to ensure that the
      *  graph is populated, but then delegate to the PublisherService immediately at the end... ie {@link org.apache.isis.schema.ixn.v2.InteractionDto}s are published as we go, not all in a batch at the end.
      */
+    // tag::refguide[]
     public List<Execution<?,?>> getExecutions() {
+        // end::refguide[]
+
         return Collections.unmodifiableList(executionGraphs);
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * The current (most recently pushed) {@link Execution}.
      */
+    // tag::refguide[]
     @Getter
     private Execution<?,?> currentExecution;
 
+    // end::refguide[]
     /**
      * The execution that preceded the current one.
      */
+    // tag::refguide[]
     @Getter
     private Execution<?,?> priorExecution;
 
-// end::refguide[]
+    // end::refguide[]
     /**
      * <b>NOT API</b>: intended to be called only by the framework.
      *
@@ -270,51 +281,69 @@ public class Interaction implements HasUniqueId {
     }
 
 
-// tag::refguide-1[]
     /**
      * Enumerates the different reasons why multiple occurrences of a certain type might occur within a single
      * (top-level) interaction.
      */
+    // tag::refguide-1[]
     public enum Sequence {
 
+        // end::refguide-1[]
         /**
          * Each interaction is either an action invocation or a property edit.  There could be multiple of these,
          * typically as the result of a nested calls using the {@link WrapperFactory}.  Another reason is
          * support for bulk action invocations within a single transaction.
          */
+        // tag::refguide-1[]
         INTERACTION,
+
+        // end::refguide-1[]
         /**
          * For objects: multiple such could be dirtied and thus published as separate events.  For actions
          * invocations/property edits : multiple sub-invocations could occur if sub-invocations are made through the
          * {@link WrapperFactory}.
          */
+        // tag::refguide-1[]
         PUBLISHED_EVENT,
+
+        // end::refguide-1[]
         /**
          * There may be multiple transactions within a given interaction.
          */
+        // tag::refguide-1[]
         TRANSACTION,
         ;
+        // end::refguide-1[]
 
         public String id() {
             return Interaction.Sequence.class.getName() + "#" + name();
         }
+        // tag::refguide-1[]
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide[]
+    // tag::refguide[]
     private final Map<String, LongAdder> maxBySequence = _Maps.newHashMap();
 
+    // end::refguide[]
     /**
-     * Generates numbers in a named sequence.  The name of the sequence can be arbitrary, though note that the
-     * framework also uses this capability to generate sequence numbers corresponding to the sequences enumerated by
-     * the {@link Sequence} enum.
+     * Generates numbers in a named sequence.
+     *
+     * The name of the sequence can be arbitrary, though note that the framework also uses this capability to
+     * generate sequence numbers corresponding to the sequences enumerated by the {@link Sequence} enum.
      */
+    // tag::refguide[]
     public int next(final String sequenceId) {
+        // end::refguide[]
+
         final LongAdder adder = maxBySequence.computeIfAbsent(sequenceId, this::newAdder);
         adder.increment();
         return adder.intValue();
+
+        // tag::refguide[]
+        // ...
     }
-// end::refguide[]
+    // end::refguide[]
 
     private LongAdder newAdder(String ignore) {
         final LongAdder adder = new LongAdder();
@@ -322,38 +351,46 @@ public class Interaction implements HasUniqueId {
         return adder;
     }
 
-// tag::refguide-2[]
     /**
      * Represents an action invocation/property edit as a node in a call-stack execution graph, with sub-interactions
      * being made by way of the {@link WrapperFactory}).
      */
+    // tag::refguide-2[]
     public static abstract class Execution<T extends MemberExecutionDto, E extends AbstractDomainEvent<?>> {
 
-        // -- fields, constructor
-
         @Getter
         private final Interaction interaction;
         @Getter
         private final InteractionType interactionType;
         @Getter
         private final String memberIdentifier;
+
+        // end::refguide-2[]
         /**
          * The target of the action invocation.  If this interaction is for a mixin action, then will be the
          * mixed-in target (not the transient mixin itself).
          */
+        // tag::refguide-2[]
         @Getter
         private final Object target;
+
+        // end::refguide-2[]
         /**
          * A human-friendly description of the class of the target object.
          */
+        // tag::refguide-2[]
         @Getter
         private final String targetClass;
+
+        // end::refguide-2[]
         /**
          * The human-friendly name of the action invoked/property edited on the target object.
          */
+        // tag::refguide-2[]
         @Getter
         private final String targetMember;
 
+        // end::refguide-2[]
         protected Execution(
                 final Interaction interaction,
                 final InteractionType interactionType,
@@ -377,9 +414,11 @@ public class Interaction implements HasUniqueId {
         /**
          * The action/property that invoked this action/property edit (if any).
          */
+        // tag::refguide-2[]
         @Getter
         private Execution<?,?> parent;
 
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
@@ -393,13 +432,17 @@ public class Interaction implements HasUniqueId {
         /**
          * The actions/property edits made in turn via the {@link WrapperFactory}.
          */
+        // tag::refguide-2[]
         public List<Execution<?,?>> getChildren() {
-            return Collections.unmodifiableList(children);
-        }
+            // end::refguide-2[]
 
+            return Collections.unmodifiableList(children);
 
-        // -- event
+            // tag::refguide-2[]
+            // ...
+        }
 
+        // end::refguide-2[]
         /**
          * The domain event fired on the {@link EventBusService event bus} representing the execution of
          * this action invocation/property edit.
@@ -410,9 +453,11 @@ public class Interaction implements HasUniqueId {
          *     {@link AbstractDomainEvent.Phase#EXECUTING executing} phase.
          * </p>
          */
+        // tag::refguide-2[]
         @Getter
         private E event;
 
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
@@ -420,29 +465,35 @@ public class Interaction implements HasUniqueId {
             this.event = event;
         }
 
-
-        // -- startedAt, completedAt
-
         /**
          * The date/time at which this execution started.
          */
+        // tag::refguide-2[]
         @Getter
         private Timestamp startedAt;
 
+        // end::refguide-2[]
         /**
          * The date/time at which this execution completed.
          */
+        // tag::refguide-2[]
         @Getter
         private Timestamp completedAt;
 
         public Timestamp start(
                 final ClockService clockService,
                 final MetricsService metricsService) {
+            // end::refguide-2[]
+
             val startedAt = clockService.nowAsJavaSqlTimestamp();
             syncMetrics(When.BEFORE, startedAt, metricsService);
             return startedAt;
+
+            // tag::refguide-2[]
+            // ...
         }
 
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
@@ -452,7 +503,6 @@ public class Interaction implements HasUniqueId {
             syncMetrics(When.AFTER, completedAt, metricsService);
         }
 
-
         /**
          * The object returned by the action invocation/property edit.
          *
@@ -464,9 +514,11 @@ public class Interaction implements HasUniqueId {
          * For <tt>void</tt> methods and for actions returning collections, the value
          * will be <tt>null</tt>.
          */
+        // tag::refguide-2[]
         @Getter
         private Object returned;
 
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
@@ -474,9 +526,11 @@ public class Interaction implements HasUniqueId {
             this.returned = returned;
         }
 
+        // tag::refguide-2[]
         @Getter
         private Exception threw;
 
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: intended to be called only by the framework.
          */
@@ -496,10 +550,11 @@ public class Interaction implements HasUniqueId {
          *     {@link Execution#getReturned()}) will (obviously) still be null.
          * </p>
          */
+        // tag::refguide-2[]
         @Getter
         private T dto;
 
-
+        // end::refguide-2[]
         /**
          * <b>NOT API</b>: Set by framework (implementation of {@link MemberExecutor})
          */
@@ -508,12 +563,13 @@ public class Interaction implements HasUniqueId {
         }
 
 
-
         // -- helpers (syncMetrics)
 
-// tag::refguide-2a[]
+        // tag::refguide-2a[]
         enum When {
             BEFORE {
+                // end::refguide-2a[]
+
                 @Override
                 void syncMetrics(
                         final Execution<?, ?> execution,
@@ -533,8 +589,12 @@ public class Interaction implements HasUniqueId {
                     numberObjectsDirtiedFor(objectCountsDto).setBefore(numberObjectsDirtied);
                 }
 
+                // tag::refguide-2a[]
+                // ....
             },
             AFTER {
+                // end::refguide-2a[]
+
                 @Override void syncMetrics(
                         final Execution<?, ?> execution,
                         final Timestamp timestamp,
@@ -553,7 +613,10 @@ public class Interaction implements HasUniqueId {
                     numberObjectsDirtiedFor(objectCountsDto).setAfter(numberObjectsDirtied);
                 }
 
+                // tag::refguide-2a[]
+                // ....
             };
+            // end::refguide-2a[]
 
             // -- helpers
 
@@ -582,7 +645,10 @@ public class Interaction implements HasUniqueId {
                     final Timestamp timestamp,
                     final int numberObjectsLoaded,
                     final int numberObjectsDirtied);
+            // tag::refguide-2a[]
         }
+        // end::refguide-2a[]
+
         private void syncMetrics(
                 final When when,
                 final Timestamp timestamp,
@@ -593,16 +659,17 @@ public class Interaction implements HasUniqueId {
 
             when.syncMetrics(this, timestamp, numberObjectsLoaded, numberObjectsDirtied);
         }
-// end::refguide-2a[]
 
+        // tag::refguide-2[]
     }
-// end::refguide-2[]
+    // end::refguide-2[]
 
-// tag::refguide-3[]
+    // tag::refguide-3[]
     public static class ActionInvocation extends Execution<ActionInvocationDto, ActionDomainEvent<?>> {
 
         @Getter
         private final List<Object> args;
+        // end::refguide-3[]
 
         public ActionInvocation(
                 final Interaction interaction,
@@ -614,14 +681,17 @@ public class Interaction implements HasUniqueId {
             super(interaction, InteractionType.ACTION_INVOCATION, memberId, target, targetMember, targetClass);
             this.args = args;
         }
+        // tag::refguide-3[]
+        // ...
     }
-// end::refguide-3[]
+    // end::refguide-3[]
 
-// tag::refguide-4[]
+    // tag::refguide-4[]
     public static class PropertyEdit extends Execution<PropertyEditDto, PropertyDomainEvent<?,?>> {
 
         @Getter
         private final Object newValue;
+        // end::refguide-4[]
 
         public PropertyEdit(
                 final Interaction interaction,
@@ -633,9 +703,12 @@ public class Interaction implements HasUniqueId {
             super(interaction, InteractionType.PROPERTY_EDIT, memberId, target, targetMember, targetClass);
             this.newValue = newValue;
         }
+
+        // tag::refguide-4[]
+        // ...
     }
-// end::refguide-4[]
+    // end::refguide-4[]
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/iactn/InteractionContext.java b/api/applib/src/main/java/org/apache/isis/applib/services/iactn/InteractionContext.java
index a3899aa..b51c596 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/iactn/InteractionContext.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/iactn/InteractionContext.java
@@ -51,7 +51,7 @@ import lombok.extern.log4j.Log4j2;
 @Log4j2
 public class InteractionContext {
 
-// end::refguide[]
+    // end::refguide[]
     public InteractionContext() {
         log.debug("init");
     }
@@ -66,13 +66,13 @@ public class InteractionContext {
         log.debug("preDestroy");
     }
 
-// tag::refguide[]
     /**
      * The currently active {@link Interaction} for this thread.
      */
+    // tag::refguide[]
     @Getter
     private Interaction interaction;
-// end::refguide[]
+    // end::refguide[]
 
     /**
      * <b>NOT API</b>: intended to be called only by the framework.
@@ -80,6 +80,7 @@ public class InteractionContext {
     public void setInteraction(final Interaction interaction) {
         this.interaction = interaction;
     }
-// tag::refguide[]
+
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/inject/ServiceInjector.java b/api/applib/src/main/java/org/apache/isis/applib/services/inject/ServiceInjector.java
index ea7e137..dcfee4a 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/inject/ServiceInjector.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/inject/ServiceInjector.java
@@ -39,6 +39,8 @@ public interface ServiceInjector {
     <T> T injectServicesInto(final T domainObject, Consumer<InjectionPoint> onNotResolvable);
 
     default <T> T injectServicesInto(final T domainObject) {
+        // end::refguide[]
+
         return injectServicesInto(domainObject, injectionPoint->{
 
             val injectionPointName = injectionPoint.toString();
@@ -51,6 +53,9 @@ public interface ServiceInjector {
             throw new NoSuchElementException(msg);
         });
 
+        // tag::refguide[]
+        // ...
     }
+
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java b/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java
index ad86f6a..61bafdc 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/jaxb/JaxbService.java
@@ -47,14 +47,18 @@ public interface JaxbService {
 
     Object fromXml(JAXBContext jaxbContext, String xml, Map<String,Object> unmarshallerProperties);
 
+    // end::refguide[]
     /**
      * As {@link #fromXml(JAXBContext, String)}, but downcast to a specific type.
      */
+    // tag::refguide[]
     <T> T fromXml(Class<T> domainClass, String xml);
 
+    // end::refguide[]
     /**
      * As {@link #fromXml(JAXBContext, String, Map)}, but downcast to a specific type.
      */
+    // tag::refguide[]
     <T> T fromXml(Class<T> domainClass, String xml, Map<String,Object> unmarshallerProperties);
 
     String toXml(final Object domainObject);
@@ -75,10 +79,11 @@ public interface JaxbService {
      *     <a href="http://isis.apache.org/schema">downloaded</a> from the Isis website.
      * </p>
      */
+    // tag::refguide[]
     enum IsisSchemas {
         INCLUDE,
         IGNORE;
-// end::refguide[]
+        // end::refguide[]
 
         /**
          * Implementation note: not using subclasses, otherwise the key in translations.po becomes more complex.
@@ -90,12 +95,12 @@ public interface JaxbService {
                 return namespaceUri.matches(".*isis\\.apache\\.org.*");
             }
         }
-// tag::refguide[]
+        // tag::refguide[]
     }
 
     Map<String, String> toXsd(final Object domainObject, final IsisSchemas isisSchemas);
 
-// end::refguide[]
+    // end::refguide[]
     class Simple implements JaxbService {
 
         @Override
@@ -245,6 +250,7 @@ public interface JaxbService {
             }
         }
     }
-// tag::refguide[]
+
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java b/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java
index 598cc6c..a0fb471 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/layout/LayoutService.java
@@ -25,15 +25,17 @@ import org.apache.isis.applib.services.menu.MenuBarsService;
 // tag::refguide[]
 public interface LayoutService {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+
     /**
      * Mode of operation when downloading a layout file (while prototyping). It affects the way the file's
      * content is assembled. Once a layout file is in place, its layout data takes precedence over any
      * conflicting layout data from annotations.
      */
+    // tag::refguide-1[]
     enum Style {
 
+        // end::refguide-1[]
         /**
          * The current layout for the domain class.
          * <p>
@@ -43,8 +45,10 @@ public interface LayoutService {
          * {@link org.apache.isis.applib.services.grid.GridService#defaultGridFor(Class) default grid},
          * also {@link org.apache.isis.applib.services.grid.GridService#normalize(Grid) normalized}.
          */
+        // tag::refguide-1[]
         CURRENT,
 
+        // end::refguide-1[]
         /**
          * As per {@link #NORMALIZED}, but also with all (non-null) facets for all
          * properties/collections/actions also included included in the grid.
@@ -56,13 +60,15 @@ public interface LayoutService {
          * <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>serialized as XML</b></li>
          * </ul>
          */
+        // tag::refguide-1[]
         COMPLETE,
 
+        // end::refguide-1[]
         /**
          * Default, whereby missing properties/collections/actions are added to regions,
          * and unused/empty regions are removed/trimmed.
          * <p>
-         * It should be possible to remove any {@link MemberOrder} and {@link MemberGroupLayout} annotation but
+         * It should be possible to remove any {@link MemberOrder} annotation but
          * any property/collection/action layout annotations would need to be retained.
          * <ul>
          * <li>{@code @MemberGroupLayout}: <b>serialized as XML</b></li>
@@ -70,8 +76,10 @@ public interface LayoutService {
          * <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>ignored</b></li>
          * </ul>
          */
+        // tag::refguide-1[]
         NORMALIZED,
 
+        // end::refguide-1[]
         /**
          * As per {@link #NORMALIZED}, but with no properties/collections/actions.
          * <p>
@@ -83,25 +91,31 @@ public interface LayoutService {
          * <li>{@code @ActionLayout, @PropertyLayout, @CollectionLayout}: <b>ignored</b></li>
          * </ul>
          */
+        // tag::refguide-1[]
         MINIMAL
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide[]
+    // end::refguide[]
     /**
      * Obtains the serialized XML form of the layout (grid) for the specified domain class.
      */
+    // tag::refguide[]
     String toXml(Class<?> domainClass, Style style);
 
+    // end::refguide[]
     /**
      * Obtains a zip file of the serialized XML of the layouts (grids) of all domain entities and view models.
      */
+    // tag::refguide[]
     byte[] toZip(final Style style);
 
+    // end::refguide[]
     /**
      * Obtains the serialized XML form of the menu bars layout ({@link MenuBarsService}).
      * @param type - either the current menubars (could be loaded from a file) or the fallback (obtained from metamodel facets)
      */
+    // tag::refguide[]
     String toMenuBarsXml(final MenuBarsService.Type type);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/linking/DeepLinkService.java b/api/applib/src/main/java/org/apache/isis/applib/services/linking/DeepLinkService.java
index 963eafe..ef3ef9c 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/linking/DeepLinkService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/linking/DeepLinkService.java
@@ -33,10 +33,12 @@ import org.apache.isis.applib.annotation.Programmatic;
 // tag::refguide[]
 public interface DeepLinkService {
 
+    // end::refguide[]
     /**
      * Creates a URI that can be used to obtain a representation of the provided domain object in one of the
      * Isis viewers.
      */
+    // tag::refguide[]
     URI deepLinkFor(Object domainObject);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsLoaderService.java b/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsLoaderService.java
index baadf11..5ca9688 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsLoaderService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsLoaderService.java
@@ -24,14 +24,18 @@ import org.apache.isis.applib.layout.menubars.bootstrap3.BS3MenuBars;
 // tag::refguide[]
 public interface MenuBarsLoaderService {
 
+    // end::refguide[]
     /**
      * Whether dynamic reloading of layouts is enabled.
      */
+    // tag::refguide[]
     boolean supportsReloading();
 
+    // end::refguide[]
     /**
      * Returns a new instance of a {@link BS3MenuBars}, else <tt>null</tt>.
      */
+    // tag::refguide[]
     BS3MenuBars menuBars();
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsService.java b/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsService.java
index 940d762..10197af 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/menu/MenuBarsService.java
@@ -23,29 +23,34 @@ import org.apache.isis.applib.layout.menubars.MenuBars;
 // tag::refguide[]
 public interface MenuBarsService {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     enum Type {
 
+        // end::refguide-1[]
         /**
          * Either derived from annotations or as obtained elsewhere
          * (eg using the {@link MenuBarsLoaderService} if the
          * default implementation of this service is in use).
          */
+        // tag::refguide-1[]
         DEFAULT,
 
+        // end::refguide-1[]
         /**
          * As derived from annotations.
          */
+        // tag::refguide-1[]
         FALLBACK
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-1[]
+
 
     /**
      * Returns {@link #menuBars()} with a type of {@link Type#DEFAULT}.
      * @return
      */
+    // tag::refguide[]
     default MenuBars menuBars() {
         return menuBars(Type.DEFAULT);
     }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/message/MessageService.java b/api/applib/src/main/java/org/apache/isis/applib/services/message/MessageService.java
index dcfc3dc..b2e32d6 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/message/MessageService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/message/MessageService.java
@@ -25,6 +25,7 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
 // tag::refguide[]
 public interface MessageService {
 
+    // end::refguide[]
     /**
      * Make the specified message available to the user. Note this will probably
      * be displayed in transitory fashion, so is only suitable for useful but
@@ -34,8 +35,10 @@ public interface MessageService {
      * @see #warnUser(String)
      * @see #raiseError(String)
      */
+    // tag::refguide[]
     void informUser(String message);
 
+    // end::refguide[]
     /**
      * Make the specified message available to the user, translated (if possible) to user's locale.
      *
@@ -49,13 +52,17 @@ public interface MessageService {
      * @see #warnUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      * @see #raiseError(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      */
+    // tag::refguide[]
     String informUser(TranslatableString message, final Class<?> contextClass, final String contextMethod);
 
+    // end::refguide[]
     /**
      * Override of {@link MessageService#informUser(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
      */
+    // tag::refguide[]
     String informUser(TranslatableString message, final String translationContext);
 
+    // end::refguide[]
     /**
      * Warn the user about a situation with the specified message. The container
      * should guarantee to display this warning to the user, and will typically
@@ -65,8 +72,10 @@ public interface MessageService {
      * @see #raiseError(String)
      * @see #informUser(String)
      */
+    // tag::refguide[]
     void warnUser(String message);
 
+    // end::refguide[]
     /**
      * Warn the user about a situation with the specified message, translated (if possible) to user's locale.
      *
@@ -80,13 +89,17 @@ public interface MessageService {
      * @see #informUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      * @see #raiseError(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      */
+    // tag::refguide[]
     String warnUser(TranslatableString message, final Class<?> contextClass, final String contextMethod);
 
+    // end::refguide[]
     /**
      * Override of {@link MessageService#warnUser(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
      */
+    // tag::refguide[]
     String warnUser(TranslatableString message, final String translationContext);
 
+    // end::refguide[]
     /**
      * Notify the user of an application error with the specified message. Note
      * this will probably be displayed in an alarming fashion, so is only
@@ -96,8 +109,10 @@ public interface MessageService {
      * @see #warnUser(String)
      * @see #informUser(String)
      */
+    // tag::refguide[]
     void raiseError(String message);
 
+    // end::refguide[]
     /**
      * Notify the user of an application error with the specified message, translated (if possible) to user's locale.
      *
@@ -111,11 +126,14 @@ public interface MessageService {
      * @see #informUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      * @see #warnUser(org.apache.isis.applib.services.i18n.TranslatableString, Class, String)
      */
+    // tag::refguide[]
     String raiseError(TranslatableString message, final Class<?> contextClass, final String contextMethod);
 
+    // end::refguide[]
     /**
      * Override of {@link MessageService#raiseError(TranslatableString, Class, String)}, but with last two parameters combined into a context string.
      */
+    // tag::refguide[]
     String raiseError(TranslatableString message, final String translationContext);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainMember.java b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainMember.java
index a696ab9..5a1f5a5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainMember.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainMember.java
@@ -18,37 +18,31 @@
  */
 package org.apache.isis.applib.services.metamodel;
 
+// tag::refguide[]
 public interface DomainMember extends Comparable<DomainMember> {
 
     String getClassType();
 
     String getClassName();
-
     String getPackageName();
 
     String getType();
 
     String getMemberName();
-
     String getNumParams();
 
     boolean isContributed();
-
     String getContributedBy();
 
     boolean isMixedIn();
-
     String getMixin();
 
     String getHidden();
-
     String getDisabled();
+    String getValidate();
 
     String getChoices();
-
     String getAutoComplete();
-
     String getDefault();
-
-    String getValidate();
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
index 0ba797f..2a0127d 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/DomainModel.java
@@ -20,8 +20,10 @@ package org.apache.isis.applib.services.metamodel;
 
 import java.util.List;
 
+// tag::refguide[]
 public interface DomainModel {
 
     List<DomainMember> getDomainMembers();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/MetaModelService.java b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/MetaModelService.java
index 6d820b0..dd2ebf5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/MetaModelService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/metamodel/MetaModelService.java
@@ -43,18 +43,23 @@ import lombok.val;
 // tag::refguide[]
 public interface MetaModelService {
 
+    // end::refguide[]
     /**
      * Provides a reverse lookup of a domain class' object type, as defined by {@link DomainObject#objectType()} (or any other mechanism that corresponds to Isis' <code>ObjectSpecIdFacet</code>).
      */
+    // tag::refguide[]
     Class<?> fromObjectType(final String objectType);
 
+    // end::refguide[]
     /**
      * Provides a lookup of a domain class' object type, as defined by {@link DomainObject#objectType()} (or any other mechanism that corresponds to Isis' <code>ObjectSpecIdFacet</code>).
      */
+    // tag::refguide[]
     String toObjectType(final Class<?> domainType);
 
     void rebuild(final Class<?> domainType);
 
+    // end::refguide[]
     /**
      * Returns a list of representations of each of member of each domain class.
      *
@@ -67,6 +72,7 @@ public interface MetaModelService {
      * </p>
      *
      */
+    // tag::refguide[]
     DomainModel getDomainModel();
 
     BeanSort sortOf(Class<?> domainType, Mode mode);
@@ -75,22 +81,28 @@ public interface MetaModelService {
 
     CommandDtoProcessor commandDtoProcessorFor(String memberIdentifier);
 
-// end::refguide[]
-
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     enum Mode {
+
+        // end::refguide-1[]
         /**
          * If the {@link #sortOf(Class, Mode) sort of} object type is unknown, then throw an exception.
          */
+        // tag::refguide-1[]
         STRICT,
+
+        // end::refguide-1[]
         /**
          * If the {@link #sortOf(Class, Mode) sort of} object type is unknown, then return {@link Sort#UNKNOWN}.
          */
+        // tag::refguide-1[]
         RELAXED
+
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide-2[]
+    // tag::refguide-2[]
     class Config {
 
         private static final int IGNORE_NOOP_FACETS = 1;
@@ -182,10 +194,9 @@ public interface MetaModelService {
         }
 
     }
-// end::refguide-2[]
-
-// tag::refguide[]
+    // end::refguide-2[]
 
+    // tag::refguide[]
     MetamodelDto exportMetaModel(final Config config);
 
 }
diff --git a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/bookmarks/BookmarkServiceDefault.java b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/bookmarks/BookmarkServiceDefault.java
index c80a5e8..17925aa 100644
--- a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/bookmarks/BookmarkServiceDefault.java
+++ b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/bookmarks/BookmarkServiceDefault.java
@@ -121,7 +121,9 @@ public class BookmarkServiceDefault implements BookmarkService, SerializingAdapt
         if(bookmark == null) {
             return null;
         }
-        //FIXME[2112] why would we ever store Service Beans as Bookmarks?        
+        //FIXME[2112] why would we ever store Service Beans as Bookmarks?
+        // - ANSWER: because it might be used by the CommandService to replay a command or exec in the background.
+        //
         //        final String objectType = bookmark.getObjectType();
         //        final Object service = lookupService(objectType);
         //        if(service != null) {