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 12:33:53 UTC

[isis] branch master updated (df9e8bc -> 33cd680)

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

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


    from df9e8bc  ISIS-2062: sync examples, adds in tags for refguide
     new 4984c0c  ISIS-2062: adds tags into applib classes for refguide docs
     new 33cd680  ISIS-2062: updates examples

The 2 revisions listed above as "new" are entirely new to this
repository and will be described in separate emails.  The revisions
listed as "add" were already present in the repository and have only
been added to this reference.


Summary of changes:
 .../applib-ant/examples/annotation/Action.java     |  61 ++++---
 .../examples/annotation/ActionLayout.java          |  51 +++---
 .../applib-ant/examples/annotation/Auditing.java   |  15 ++
 .../examples/annotation/BookmarkPolicy.java        |  17 +-
 .../applib-ant/examples/annotation/Bounding.java   |   2 +
 .../applib-ant/examples/annotation/Collection.java |  39 +++--
 .../examples/annotation/CollectionLayout.java      |  44 ++---
 .../examples/annotation/CommandExecuteIn.java      |  22 +--
 .../examples/annotation/CommandPersistence.java    |  16 +-
 .../examples/annotation/CommandReification.java    |  15 ++
 .../applib-ant/examples/annotation/Constants.java  |  27 ---
 .../examples/annotation/Contributed.java           |  20 ++-
 .../applib-ant/examples/annotation/Defaulted.java  |   6 +
 .../examples/annotation/DomainObject.java          |  82 +++++----
 .../examples/annotation/DomainObjectLayout.java    |  56 ++++---
 .../examples/annotation/DomainService.java         |  23 ++-
 .../examples/annotation/DomainServiceLayout.java   |  17 +-
 .../applib-ant/examples/annotation/Editing.java    |  14 ++
 .../examples/annotation/EqualByContent.java        |   7 +-
 .../applib-ant/examples/annotation/Facets.java     |   7 +
 .../applib-ant/examples/annotation/HomePage.java   |   2 +
 .../examples/annotation/LabelPosition.java         |   9 +-
 .../examples/annotation/MemberOrder.java           |   6 +
 .../examples/annotation/MementoSerialization.java  |  12 ++
 .../applib-ant/examples/annotation/MinLength.java  |   3 +-
 .../applib-ant/examples/annotation/Mixin.java      |   6 +
 .../applib-ant/examples/annotation/Module.java     |   5 +-
 .../applib-ant/examples/annotation/Nature.java     |  29 +++-
 .../examples/annotation/NatureOfService.java       |  31 ++--
 .../applib-ant/examples/annotation/Navigable.java  |   9 +-
 .../examples/annotation/Optionality.java           |  27 ++-
 .../examples/annotation/OrderPrecedence.java       |  13 ++
 .../applib-ant/examples/annotation/Parameter.java  |  32 ++--
 .../examples/annotation/ParameterLayout.java       |  24 ++-
 .../examples/annotation/Programmatic.java          |  13 +-
 .../applib-ant/examples/annotation/Projecting.java |   8 +
 .../examples/annotation/PromptStyle.java           |  27 ++-
 .../applib-ant/examples/annotation/Property.java   |  92 +++++-----
 .../examples/annotation/PropertyLayout.java        |  26 ++-
 .../applib-ant/examples/annotation/Publishing.java |  15 ++
 .../examples/annotation/PublishingChangeKind.java  |   8 +-
 .../applib-ant/examples/annotation/Redirect.java   |  10 ++
 .../applib-ant/examples/annotation/RenderDay.java  |  12 +-
 .../applib-ant/examples/annotation/Repainting.java |  10 ++
 .../applib-ant/examples/annotation/RestrictTo.java |   6 +
 .../examples/annotation/SemanticsOf.java           |  35 +++-
 .../applib-ant/examples/annotation/Title.java      |  16 +-
 .../applib-ant/examples/annotation/Value.java      |   6 +
 .../applib-ant/examples/annotation/ViewModel.java  |  14 +-
 .../examples/annotation/ViewModelLayout.java       |  55 +++---
 .../applib-ant/examples/annotation/Where.java      |  65 ++++++++
 .../examples/events}/EventObjectBase.java          |  20 ++-
 .../events/domain/AbstractDomainEvent.java         | 185 +++++++++++++--------
 .../examples/events/domain/ActionDomainEvent.java  | 152 +++++++----------
 .../events/domain/CollectionDomainEvent.java       |  62 +++----
 .../events/domain/PropertyDomainEvent.java         |  55 +++---
 .../events/lifecycle/AbstractLifecycleEvent.java   |   6 +-
 .../events/lifecycle/ObjectCreatedEvent.java       |  23 +--
 .../events/lifecycle/ObjectLoadedEvent.java        |  25 +--
 .../events/lifecycle/ObjectPersistedEvent.java     |  24 +--
 .../events/lifecycle/ObjectPersistingEvent.java    |  22 +--
 .../events/lifecycle/ObjectRemovingEvent.java      |  22 +--
 .../events/lifecycle/ObjectUpdatedEvent.java       |  22 +--
 .../events/lifecycle/ObjectUpdatingEvent.java      |  22 +--
 .../examples/events/ui/AbstractUiEvent.java        |  11 +-
 .../examples/events/ui/CssClassUiEvent.java        |  56 ++++---
 .../examples/events/ui/LayoutUiEvent.java          |  64 ++++---
 .../applib-cm/examples/events/ui/TitleUiEvent.java |  45 ++---
 .../modules/applib-cm/examples/graph/Edge.java     |   7 +-
 .../applib-cm/examples/graph/SimpleEdge.java       |   2 +
 .../modules/applib-cm/examples/graph/Vertex.java   |  15 +-
 .../applib-cm/examples/security/RoleMemento.java   |  27 ++-
 .../applib-cm/examples/security/UserMemento.java   |  73 ++++----
 .../examples/spec/AbstractSpecification2.java      |   2 +
 .../applib-cm/examples/spec/Specification.java     |   7 +-
 .../applib-cm/examples/spec/Specification2.java    |   7 +-
 .../applib-cm/examples/spec/SpecificationAnd.java  |   2 +
 .../applib-cm/examples/spec/SpecificationNot.java  |   2 +
 .../applib-cm/examples/spec/SpecificationOr.java   |   4 +-
 .../modules/applib-cm/examples/util/Enums.java     |   5 +-
 .../modules/applib-cm/examples/util/JaxbUtil.java  |   4 +-
 .../modules/applib-cm/examples/value/Blob.java     |   2 +
 .../modules/applib-cm/examples/value/Clob.java     |   2 +
 .../modules/applib-cm/examples/value/Image.java    |   2 +
 .../examples/value/LocalResourcePath.java          |   2 +
 .../modules/applib-cm/examples/value/Markup.java   |   2 +
 .../examples/value/NamedWithMimeType.java          |   2 +
 .../modules/applib-cm/examples/value/Password.java |   2 +
 .../applib-svc/examples/services/HasUniqueId.java  |   4 +
 .../applib-svc/examples/services/HasUsername.java  |   4 +-
 .../examples/services/WithTransactionScope.java    |   2 +
 .../examples/services/metrics/MetricsService.java  |   4 +
 .../services/publish/PublishedObjects.java         |   3 -
 .../services/publish/PublisherService.java         |   2 +
 .../queryresultscache/QueryResultsCache.java       |  14 +-
 .../services/registry/ServiceRegistry.java         |  40 ++++-
 .../examples/services/repository/EntityState.java  |   8 +-
 .../services/repository/RepositoryService.java     |  35 +++-
 .../examples/services/routing/RoutingService.java  |   1 -
 .../examples/services/scratchpad/Scratchpad.java   |  12 +-
 .../services/session/SessionLoggingService.java    |  11 +-
 .../examples/services/sudo/SudoService.java        |  40 +++--
 .../examples/services/swagger/SwaggerService.java  |  26 ++-
 .../services/tablecol/TableColumnOrderService.java |   3 -
 .../examples/services/title/TitleService.java      |   4 +
 .../services/urlencoding/UrlEncodingService.java   |   1 +
 .../examples/services/user/UserService.java        |   2 +
 .../services/userprof/UserProfileService.java      |   2 +
 .../services/userreg/EmailNotificationService.java |   8 +-
 .../examples/services/userreg/UserDetails.java     |   3 +-
 .../examples/services/wrapper/WrapperFactory.java  | 106 +++++++++---
 .../examples/services/wrapper/WrappingObject.java  |  11 +-
 .../services/wrapper/events/InteractionEvent.java  |   2 +-
 .../examples/services/xactn/Transaction.java       |   2 +
 .../examples/services/xactn/TransactionId.java     |  12 +-
 .../services/xactn/TransactionService.java         |  26 ++-
 .../examples/services/xactn/TransactionState.java  |  24 ++-
 .../services/xmlsnapshot/XmlSnapshotService.java   |  24 ++-
 .../org/apache/isis/applib/AbstractViewModel.java  |   2 +
 .../apache/isis/applib/ApplicationException.java   |   2 +
 .../org/apache/isis/applib/FatalException.java     |   2 +
 .../java/org/apache/isis/applib/Identifier.java    |   2 +
 .../isis/applib/NonRecoverableException.java       |   2 +
 .../apache/isis/applib/PersistFailedException.java |   2 +
 .../apache/isis/applib/RecoverableException.java   |   2 +
 .../isis/applib/RecreatableDomainObject.java       |   2 +
 .../apache/isis/applib/RepositoryException.java    |   2 +
 .../java/org/apache/isis/applib/ViewModel.java     |   2 +
 .../isis/applib/adapters/DefaultsProvider.java     |   4 +
 .../isis/applib/adapters/EncoderDecoder.java       |   8 +-
 .../isis/applib/adapters/EncodingException.java    |   2 +
 .../org/apache/isis/applib/adapters/Parser.java    |  14 ++
 .../isis/applib/adapters/ParsingException.java     |   2 +
 .../applib/adapters/ValueSemanticsProvider.java    |   8 +
 .../org/apache/isis/applib/annotation/Action.java  |  61 ++++---
 .../isis/applib/annotation/ActionLayout.java       |  51 +++---
 .../apache/isis/applib/annotation/Auditing.java    |  15 ++
 .../isis/applib/annotation/BookmarkPolicy.java     |  17 +-
 .../apache/isis/applib/annotation/Bounding.java    |   2 +
 .../apache/isis/applib/annotation/Collection.java  |  39 +++--
 .../isis/applib/annotation/CollectionLayout.java   |  44 ++---
 .../isis/applib/annotation/CommandExecuteIn.java   |  22 +--
 .../isis/applib/annotation/CommandPersistence.java |  16 +-
 .../isis/applib/annotation/CommandReification.java |  15 ++
 .../apache/isis/applib/annotation/Constants.java   |  27 ---
 .../apache/isis/applib/annotation/Contributed.java |  20 ++-
 .../apache/isis/applib/annotation/Defaulted.java   |   6 +
 .../isis/applib/annotation/DomainObject.java       |  82 +++++----
 .../isis/applib/annotation/DomainObjectLayout.java |  56 ++++---
 .../isis/applib/annotation/DomainService.java      |  23 ++-
 .../applib/annotation/DomainServiceLayout.java     |  17 +-
 .../org/apache/isis/applib/annotation/Editing.java |  14 ++
 .../isis/applib/annotation/EqualByContent.java     |   7 +-
 .../org/apache/isis/applib/annotation/Facets.java  |   7 +
 .../apache/isis/applib/annotation/HomePage.java    |   2 +
 .../isis/applib/annotation/LabelPosition.java      |   9 +-
 .../apache/isis/applib/annotation/MemberOrder.java |   6 +
 .../applib/annotation/MementoSerialization.java    |  12 ++
 .../apache/isis/applib/annotation/MinLength.java   |   3 +-
 .../org/apache/isis/applib/annotation/Mixin.java   |   6 +
 .../org/apache/isis/applib/annotation/Module.java  |   5 +-
 .../org/apache/isis/applib/annotation/Nature.java  |  29 +++-
 .../isis/applib/annotation/NatureOfService.java    |  31 ++--
 .../apache/isis/applib/annotation/Navigable.java   |   9 +-
 .../apache/isis/applib/annotation/Optionality.java |  27 ++-
 .../isis/applib/annotation/OrderPrecedence.java    |  13 ++
 .../apache/isis/applib/annotation/Parameter.java   |  32 ++--
 .../isis/applib/annotation/ParameterLayout.java    |  24 ++-
 .../isis/applib/annotation/Programmatic.java       |  13 +-
 .../apache/isis/applib/annotation/Projecting.java  |   8 +
 .../apache/isis/applib/annotation/PromptStyle.java |  27 ++-
 .../apache/isis/applib/annotation/Property.java    |  92 +++++-----
 .../isis/applib/annotation/PropertyLayout.java     |  26 ++-
 .../apache/isis/applib/annotation/Publishing.java  |  15 ++
 .../applib/annotation/PublishingChangeKind.java    |   8 +-
 .../apache/isis/applib/annotation/Redirect.java    |  10 ++
 .../apache/isis/applib/annotation/RenderDay.java   |  12 +-
 .../apache/isis/applib/annotation/Repainting.java  |  10 ++
 .../apache/isis/applib/annotation/RestrictTo.java  |   6 +
 .../apache/isis/applib/annotation/SemanticsOf.java |  35 +++-
 .../org/apache/isis/applib/annotation/Title.java   |  16 +-
 .../org/apache/isis/applib/annotation/Value.java   |   6 +
 .../apache/isis/applib/annotation/ViewModel.java   |  14 +-
 .../isis/applib/annotation/ViewModelLayout.java    |  55 +++---
 .../org/apache/isis/applib/annotation/Where.java   |  65 ++++++++
 .../apache/isis/applib/client/SuppressionType.java |  48 ++++--
 .../isis/applib/events}/EventObjectBase.java       |  20 ++-
 .../applib/events/domain/AbstractDomainEvent.java  | 185 +++++++++++++--------
 .../applib/events/domain/ActionDomainEvent.java    | 152 +++++++----------
 .../events/domain/CollectionDomainEvent.java       |  62 +++----
 .../applib/events/domain/PropertyDomainEvent.java  |  55 +++---
 .../events/lifecycle/AbstractLifecycleEvent.java   |   6 +-
 .../events/lifecycle/ObjectCreatedEvent.java       |  23 +--
 .../applib/events/lifecycle/ObjectLoadedEvent.java |  25 +--
 .../events/lifecycle/ObjectPersistedEvent.java     |  24 +--
 .../events/lifecycle/ObjectPersistingEvent.java    |  22 +--
 .../events/lifecycle/ObjectRemovingEvent.java      |  22 +--
 .../events/lifecycle/ObjectUpdatedEvent.java       |  22 +--
 .../events/lifecycle/ObjectUpdatingEvent.java      |  22 +--
 .../isis/applib/events/ui/AbstractUiEvent.java     |  11 +-
 .../isis/applib/events/ui/CssClassUiEvent.java     |  56 ++++---
 .../isis/applib/events/ui/LayoutUiEvent.java       |  64 ++++---
 .../apache/isis/applib/events/ui/TitleUiEvent.java |  45 ++---
 .../java/org/apache/isis/applib/graph/Edge.java    |   7 +-
 .../org/apache/isis/applib/graph/SimpleEdge.java   |   2 +
 .../java/org/apache/isis/applib/graph/Vertex.java  |  15 +-
 .../jaxbadapters/PersistentEntitiesAdapter.java    |  22 ++-
 .../jaxbadapters/PersistentEntityAdapter.java      |  15 +-
 .../java/org/apache/isis/applib/query/Query.java   |  24 ++-
 .../apache/isis/applib/security/RoleMemento.java   |  27 ++-
 .../apache/isis/applib/security/UserMemento.java   |  73 ++++----
 .../apache/isis/applib/services/HasUniqueId.java   |   4 +
 .../apache/isis/applib/services/HasUsername.java   |   4 +-
 .../isis/applib/services/WithTransactionScope.java |   2 +
 .../applib/services/metrics/MetricsService.java    |   4 +
 .../applib/services/publish/PublishedObjects.java  |   3 -
 .../applib/services/publish/PublisherService.java  |   2 +
 .../queryresultscache/QueryResultsCache.java       |  14 +-
 .../applib/services/registry/ServiceRegistry.java  |  40 ++++-
 .../applib/services/repository/EntityState.java    |   8 +-
 .../services/repository/RepositoryService.java     |  35 +++-
 .../applib/services/routing/RoutingService.java    |   1 -
 .../applib/services/scratchpad/Scratchpad.java     |  12 +-
 .../services/session/SessionLoggingService.java    |  11 +-
 .../isis/applib/services/sudo/SudoService.java     |  40 +++--
 .../applib/services/swagger/SwaggerService.java    |  26 ++-
 .../services/tablecol/TableColumnOrderService.java |   3 -
 .../isis/applib/services/title/TitleService.java   |   4 +
 .../services/urlencoding/UrlEncodingService.java   |   1 +
 .../isis/applib/services/user/UserService.java     |   2 +
 .../services/userprof/UserProfileService.java      |   2 +
 .../services/userreg/EmailNotificationService.java |   8 +-
 .../isis/applib/services/userreg/UserDetails.java  |   3 +-
 .../applib/services/wrapper/WrapperFactory.java    | 106 +++++++++---
 .../applib/services/wrapper/WrappingObject.java    |  11 +-
 .../services/wrapper/events/InteractionEvent.java  |   2 +-
 .../isis/applib/services/xactn/Transaction.java    |   2 +
 .../isis/applib/services/xactn/TransactionId.java  |  12 +-
 .../applib/services/xactn/TransactionService.java  |  26 ++-
 .../applib/services/xactn/TransactionState.java    |  24 ++-
 .../services/xmlsnapshot/XmlSnapshotService.java   |  24 ++-
 .../snapshot/SnapshottableWithInclusions.java      |   5 +
 .../isis/applib/spec/AbstractSpecification2.java   |   2 +
 .../org/apache/isis/applib/spec/Specification.java |   7 +-
 .../apache/isis/applib/spec/Specification2.java    |   7 +-
 .../apache/isis/applib/spec/SpecificationAnd.java  |   2 +
 .../apache/isis/applib/spec/SpecificationNot.java  |   2 +
 .../apache/isis/applib/spec/SpecificationOr.java   |   4 +-
 .../apache/isis/applib/types/DescriptionType.java  |  10 +-
 .../isis/applib/types/MemberIdentifierType.java    |   8 +-
 .../apache/isis/applib/types/TargetActionType.java |  10 +-
 .../apache/isis/applib/types/TargetClassType.java  |  10 +-
 .../java/org/apache/isis/applib/util/Enums.java    |   5 +-
 .../java/org/apache/isis/applib/util/JaxbUtil.java |   4 +-
 .../java/org/apache/isis/applib/value/Blob.java    |   2 +
 .../java/org/apache/isis/applib/value/Clob.java    |   2 +
 .../java/org/apache/isis/applib/value/Image.java   |   2 +
 .../isis/applib/value/LocalResourcePath.java       |   2 +
 .../java/org/apache/isis/applib/value/Markup.java  |   2 +
 .../isis/applib/value/NamedWithMimeType.java       |   2 +
 .../org/apache/isis/applib/value/Password.java     |   2 +
 .../core/metamodel/facets/DomainEventHelper.java   |   2 +-
 .../transaction/ChangedObjectsService.java         |   5 +-
 .../userreg/EmailNotificationServiceDefault.java   |   1 -
 .../runtimeservices/wrapper/AsyncWrapDefault.java  |  20 +--
 .../wrapper/WrapperFactoryDefault.java             |   8 +-
 .../commons/internal/reflection/ReflectTest.java   |   9 +-
 .../wrapper/WrapperFactoryDefaultTest.java         |  12 +-
 .../testdomain/auditing/AuditerServiceTest.java    |   5 +-
 .../publishing/PublisherServiceTest.java           |   5 +-
 .../applib/events/FixturesInstalledEvent.java      |   2 +-
 .../applib/events/FixturesInstallingEvent.java     |   2 +-
 272 files changed, 3573 insertions(+), 1888 deletions(-)
 delete mode 100644 api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Constants.java
 rename api/applib/src/main/{java/org/apache/isis/applib/events/domain => adoc/modules/applib-cm/examples/events}/EventObjectBase.java (89%)
 delete mode 100644 api/applib/src/main/java/org/apache/isis/applib/annotation/Constants.java
 rename api/applib/src/main/{adoc/modules/applib-cm/examples/events/domain => java/org/apache/isis/applib/events}/EventObjectBase.java (89%)


[isis] 01/02: ISIS-2062: adds tags into applib classes for refguide docs

Posted by da...@apache.org.
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 4984c0c5f317540b481f0d07684f85c20c49b009
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Mar 3 11:39:45 2020 +0000

    ISIS-2062: adds tags into applib classes for refguide docs
---
 .../org/apache/isis/applib/AbstractViewModel.java  |   2 +
 .../apache/isis/applib/ApplicationException.java   |   2 +
 .../org/apache/isis/applib/FatalException.java     |   2 +
 .../java/org/apache/isis/applib/Identifier.java    |   2 +
 .../isis/applib/NonRecoverableException.java       |   2 +
 .../apache/isis/applib/PersistFailedException.java |   2 +
 .../apache/isis/applib/RecoverableException.java   |   2 +
 .../isis/applib/RecreatableDomainObject.java       |   2 +
 .../apache/isis/applib/RepositoryException.java    |   2 +
 .../java/org/apache/isis/applib/ViewModel.java     |   2 +
 .../isis/applib/adapters/DefaultsProvider.java     |   4 +
 .../isis/applib/adapters/EncoderDecoder.java       |   8 +-
 .../isis/applib/adapters/EncodingException.java    |   2 +
 .../org/apache/isis/applib/adapters/Parser.java    |  14 ++
 .../isis/applib/adapters/ParsingException.java     |   2 +
 .../applib/adapters/ValueSemanticsProvider.java    |   8 +
 .../org/apache/isis/applib/annotation/Action.java  |  61 ++++---
 .../isis/applib/annotation/ActionLayout.java       |  51 +++---
 .../apache/isis/applib/annotation/Auditing.java    |  15 ++
 .../isis/applib/annotation/BookmarkPolicy.java     |  17 +-
 .../apache/isis/applib/annotation/Bounding.java    |   2 +
 .../apache/isis/applib/annotation/Collection.java  |  39 +++--
 .../isis/applib/annotation/CollectionLayout.java   |  44 ++---
 .../isis/applib/annotation/CommandExecuteIn.java   |  22 +--
 .../isis/applib/annotation/CommandPersistence.java |  16 +-
 .../isis/applib/annotation/CommandReification.java |  15 ++
 .../apache/isis/applib/annotation/Constants.java   |  27 ---
 .../apache/isis/applib/annotation/Contributed.java |  20 ++-
 .../apache/isis/applib/annotation/Defaulted.java   |   6 +
 .../isis/applib/annotation/DomainObject.java       |  82 +++++----
 .../isis/applib/annotation/DomainObjectLayout.java |  56 ++++---
 .../isis/applib/annotation/DomainService.java      |  23 ++-
 .../applib/annotation/DomainServiceLayout.java     |  17 +-
 .../org/apache/isis/applib/annotation/Editing.java |  14 ++
 .../isis/applib/annotation/EqualByContent.java     |   7 +-
 .../org/apache/isis/applib/annotation/Facets.java  |   7 +
 .../apache/isis/applib/annotation/HomePage.java    |   2 +
 .../isis/applib/annotation/LabelPosition.java      |   9 +-
 .../apache/isis/applib/annotation/MemberOrder.java |   6 +
 .../applib/annotation/MementoSerialization.java    |  12 ++
 .../apache/isis/applib/annotation/MinLength.java   |   3 +-
 .../org/apache/isis/applib/annotation/Mixin.java   |   6 +
 .../org/apache/isis/applib/annotation/Module.java  |   5 +-
 .../org/apache/isis/applib/annotation/Nature.java  |  29 +++-
 .../isis/applib/annotation/NatureOfService.java    |  31 ++--
 .../apache/isis/applib/annotation/Navigable.java   |   9 +-
 .../apache/isis/applib/annotation/Optionality.java |  27 ++-
 .../isis/applib/annotation/OrderPrecedence.java    |  13 ++
 .../apache/isis/applib/annotation/Parameter.java   |  32 ++--
 .../isis/applib/annotation/ParameterLayout.java    |  24 ++-
 .../isis/applib/annotation/Programmatic.java       |  13 +-
 .../apache/isis/applib/annotation/Projecting.java  |   8 +
 .../apache/isis/applib/annotation/PromptStyle.java |  27 ++-
 .../apache/isis/applib/annotation/Property.java    |  92 +++++-----
 .../isis/applib/annotation/PropertyLayout.java     |  26 ++-
 .../apache/isis/applib/annotation/Publishing.java  |  15 ++
 .../applib/annotation/PublishingChangeKind.java    |   8 +-
 .../apache/isis/applib/annotation/Redirect.java    |  10 ++
 .../apache/isis/applib/annotation/RenderDay.java   |  12 +-
 .../apache/isis/applib/annotation/Repainting.java  |  10 ++
 .../apache/isis/applib/annotation/RestrictTo.java  |   6 +
 .../apache/isis/applib/annotation/SemanticsOf.java |  35 +++-
 .../org/apache/isis/applib/annotation/Title.java   |  16 +-
 .../org/apache/isis/applib/annotation/Value.java   |   6 +
 .../apache/isis/applib/annotation/ViewModel.java   |  14 +-
 .../isis/applib/annotation/ViewModelLayout.java    |  55 +++---
 .../org/apache/isis/applib/annotation/Where.java   |  65 ++++++++
 .../apache/isis/applib/client/SuppressionType.java |  48 ++++--
 .../events/{domain => }/EventObjectBase.java       |  20 ++-
 .../applib/events/domain/AbstractDomainEvent.java  | 185 +++++++++++++--------
 .../applib/events/domain/ActionDomainEvent.java    | 152 +++++++----------
 .../events/domain/CollectionDomainEvent.java       |  62 +++----
 .../applib/events/domain/PropertyDomainEvent.java  |  55 +++---
 .../events/lifecycle/AbstractLifecycleEvent.java   |   6 +-
 .../events/lifecycle/ObjectCreatedEvent.java       |  23 +--
 .../applib/events/lifecycle/ObjectLoadedEvent.java |  25 +--
 .../events/lifecycle/ObjectPersistedEvent.java     |  24 +--
 .../events/lifecycle/ObjectPersistingEvent.java    |  22 +--
 .../events/lifecycle/ObjectRemovingEvent.java      |  22 +--
 .../events/lifecycle/ObjectUpdatedEvent.java       |  22 +--
 .../events/lifecycle/ObjectUpdatingEvent.java      |  22 +--
 .../isis/applib/events/ui/AbstractUiEvent.java     |  11 +-
 .../isis/applib/events/ui/CssClassUiEvent.java     |  56 ++++---
 .../isis/applib/events/ui/LayoutUiEvent.java       |  64 ++++---
 .../apache/isis/applib/events/ui/TitleUiEvent.java |  45 ++---
 .../java/org/apache/isis/applib/graph/Edge.java    |   7 +-
 .../org/apache/isis/applib/graph/SimpleEdge.java   |   2 +
 .../java/org/apache/isis/applib/graph/Vertex.java  |  15 +-
 .../jaxbadapters/PersistentEntitiesAdapter.java    |  22 ++-
 .../jaxbadapters/PersistentEntityAdapter.java      |  15 +-
 .../java/org/apache/isis/applib/query/Query.java   |  24 ++-
 .../apache/isis/applib/security/RoleMemento.java   |  27 ++-
 .../apache/isis/applib/security/UserMemento.java   |  73 ++++----
 .../apache/isis/applib/services/HasUniqueId.java   |   4 +
 .../apache/isis/applib/services/HasUsername.java   |   4 +-
 .../isis/applib/services/WithTransactionScope.java |   2 +
 .../applib/services/metrics/MetricsService.java    |   4 +
 .../applib/services/publish/PublishedObjects.java  |   3 -
 .../applib/services/publish/PublisherService.java  |   2 +
 .../queryresultscache/QueryResultsCache.java       |  14 +-
 .../applib/services/registry/ServiceRegistry.java  |  40 ++++-
 .../applib/services/repository/EntityState.java    |   8 +-
 .../services/repository/RepositoryService.java     |  35 +++-
 .../applib/services/routing/RoutingService.java    |   1 -
 .../applib/services/scratchpad/Scratchpad.java     |  12 +-
 .../services/session/SessionLoggingService.java    |  11 +-
 .../isis/applib/services/sudo/SudoService.java     |  40 +++--
 .../applib/services/swagger/SwaggerService.java    |  26 ++-
 .../services/tablecol/TableColumnOrderService.java |   3 -
 .../isis/applib/services/title/TitleService.java   |   4 +
 .../services/urlencoding/UrlEncodingService.java   |   1 +
 .../isis/applib/services/user/UserService.java     |   2 +
 .../services/userprof/UserProfileService.java      |   2 +
 .../services/userreg/EmailNotificationService.java |   8 +-
 .../isis/applib/services/userreg/UserDetails.java  |   3 +-
 .../applib/services/wrapper/WrapperFactory.java    | 106 +++++++++---
 .../applib/services/wrapper/WrappingObject.java    |  11 +-
 .../services/wrapper/events/InteractionEvent.java  |   2 +-
 .../isis/applib/services/xactn/Transaction.java    |   2 +
 .../isis/applib/services/xactn/TransactionId.java  |  12 +-
 .../applib/services/xactn/TransactionService.java  |  26 ++-
 .../applib/services/xactn/TransactionState.java    |  24 ++-
 .../services/xmlsnapshot/XmlSnapshotService.java   |  24 ++-
 .../snapshot/SnapshottableWithInclusions.java      |   5 +
 .../isis/applib/spec/AbstractSpecification2.java   |   2 +
 .../org/apache/isis/applib/spec/Specification.java |   7 +-
 .../apache/isis/applib/spec/Specification2.java    |   7 +-
 .../apache/isis/applib/spec/SpecificationAnd.java  |   2 +
 .../apache/isis/applib/spec/SpecificationNot.java  |   2 +
 .../apache/isis/applib/spec/SpecificationOr.java   |   4 +-
 .../apache/isis/applib/types/DescriptionType.java  |  10 +-
 .../isis/applib/types/MemberIdentifierType.java    |   8 +-
 .../apache/isis/applib/types/TargetActionType.java |  10 +-
 .../apache/isis/applib/types/TargetClassType.java  |  10 +-
 .../java/org/apache/isis/applib/util/Enums.java    |   5 +-
 .../java/org/apache/isis/applib/util/JaxbUtil.java |   4 +-
 .../java/org/apache/isis/applib/value/Blob.java    |   2 +
 .../java/org/apache/isis/applib/value/Clob.java    |   2 +
 .../java/org/apache/isis/applib/value/Image.java   |   2 +
 .../isis/applib/value/LocalResourcePath.java       |   2 +
 .../java/org/apache/isis/applib/value/Markup.java  |   2 +
 .../isis/applib/value/NamedWithMimeType.java       |   2 +
 .../org/apache/isis/applib/value/Password.java     |   2 +
 .../core/metamodel/facets/DomainEventHelper.java   |   2 +-
 .../transaction/ChangedObjectsService.java         |   5 +-
 .../userreg/EmailNotificationServiceDefault.java   |   1 -
 .../runtimeservices/wrapper/AsyncWrapDefault.java  |  20 +--
 .../wrapper/WrapperFactoryDefault.java             |   8 +-
 .../commons/internal/reflection/ReflectTest.java   |   9 +-
 .../wrapper/WrapperFactoryDefaultTest.java         |  12 +-
 .../testdomain/auditing/AuditerServiceTest.java    |   5 +-
 .../publishing/PublisherServiceTest.java           |   5 +-
 .../applib/events/FixturesInstalledEvent.java      |   2 +-
 .../applib/events/FixturesInstallingEvent.java     |   2 +-
 154 files changed, 1885 insertions(+), 986 deletions(-)

diff --git a/api/applib/src/main/java/org/apache/isis/applib/AbstractViewModel.java b/api/applib/src/main/java/org/apache/isis/applib/AbstractViewModel.java
index 6d81128..ce2cb98 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/AbstractViewModel.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/AbstractViewModel.java
@@ -32,6 +32,8 @@ package org.apache.isis.applib;
  * </p>
  *
  */
+// tag::refguide[]
+// end::refguide[]
 public abstract class AbstractViewModel implements ViewModel {
 
     @Override
diff --git a/api/applib/src/main/java/org/apache/isis/applib/ApplicationException.java b/api/applib/src/main/java/org/apache/isis/applib/ApplicationException.java
index a48f454..5fa2858 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/ApplicationException.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/ApplicationException.java
@@ -45,6 +45,8 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
  * @see NonRecoverableException
  * @see FatalException
  */
+// tag::refguide[]
+// end::refguide[]
 public class ApplicationException extends RecoverableException {
 
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/java/org/apache/isis/applib/FatalException.java b/api/applib/src/main/java/org/apache/isis/applib/FatalException.java
index 60191a9..dadd763 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/FatalException.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/FatalException.java
@@ -34,6 +34,8 @@ package org.apache.isis.applib;
  * @see ApplicationException
  * @see NonRecoverableException
  */
+// tag::refguide[]
+// end::refguide[]
 public class FatalException extends NonRecoverableException {
 
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/java/org/apache/isis/applib/Identifier.java b/api/applib/src/main/java/org/apache/isis/applib/Identifier.java
index 7a7a2d6..bfd8f62 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/Identifier.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/Identifier.java
@@ -28,6 +28,8 @@ import java.util.stream.Collectors;
 import org.apache.isis.core.commons.internal.base._NullSafe;
 import org.apache.isis.core.commons.internal.collections._Lists;
 
+// tag::refguide[]
+// end::refguide[]
 public class Identifier implements Comparable<Identifier> {
 
     private static final List<String> EMPTY_LIST_OF_STRINGS = Collections.<String> emptyList();
diff --git a/api/applib/src/main/java/org/apache/isis/applib/NonRecoverableException.java b/api/applib/src/main/java/org/apache/isis/applib/NonRecoverableException.java
index a5ef8d0..2853e2b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/NonRecoverableException.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/NonRecoverableException.java
@@ -39,6 +39,8 @@ import org.apache.isis.core.commons.internal.functions._Functions;
  * @see ApplicationException
  * @see FatalException
  */
+// tag::refguide[]
+// end::refguide[]
 public class NonRecoverableException extends RuntimeException implements TranslatableException {
 
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/java/org/apache/isis/applib/PersistFailedException.java b/api/applib/src/main/java/org/apache/isis/applib/PersistFailedException.java
index 615f0a9..44cfe31 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/PersistFailedException.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/PersistFailedException.java
@@ -31,6 +31,8 @@ package org.apache.isis.applib;
  * @see NonRecoverableException
  * @see RecoverableException
  */
+// tag::refguide[]
+// end::refguide[]
 public class PersistFailedException extends NonRecoverableException {
 
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/java/org/apache/isis/applib/RecoverableException.java b/api/applib/src/main/java/org/apache/isis/applib/RecoverableException.java
index a52e2f5..5ff2e77 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/RecoverableException.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/RecoverableException.java
@@ -48,6 +48,8 @@ import org.apache.isis.core.commons.internal.exceptions._Exceptions;
  * @see NonRecoverableException
  * @see FatalException
  */
+// tag::refguide[]
+// end::refguide[]
 public class RecoverableException extends RuntimeException implements TranslatableException {
 
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/java/org/apache/isis/applib/RecreatableDomainObject.java b/api/applib/src/main/java/org/apache/isis/applib/RecreatableDomainObject.java
index 37e6c12..d6ede95 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/RecreatableDomainObject.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/RecreatableDomainObject.java
@@ -29,6 +29,8 @@ package org.apache.isis.applib;
  * </p>
 
  */
+// tag::refguide[]
+// end::refguide[]
 public interface RecreatableDomainObject {
 
     /**
diff --git a/api/applib/src/main/java/org/apache/isis/applib/RepositoryException.java b/api/applib/src/main/java/org/apache/isis/applib/RepositoryException.java
index af66af9..d320dc3 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/RepositoryException.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/RepositoryException.java
@@ -31,6 +31,8 @@ package org.apache.isis.applib;
  * @see NonRecoverableException
  * @see RecoverableException
  */
+// tag::refguide[]
+// end::refguide[]
 public class RepositoryException extends NonRecoverableException {
 
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/java/org/apache/isis/applib/ViewModel.java b/api/applib/src/main/java/org/apache/isis/applib/ViewModel.java
index 9fb7857..fe69f1c 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/ViewModel.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/ViewModel.java
@@ -28,6 +28,8 @@ import org.apache.isis.applib.annotation.Programmatic;
  *     Objects that are part of the domain object layer should instead implement {@link RecreatableDomainObject}.
  * </p>
  */
+// tag::refguide[]
+// end::refguide[]
 public interface ViewModel {
 
     /**
diff --git a/api/applib/src/main/java/org/apache/isis/applib/adapters/DefaultsProvider.java b/api/applib/src/main/java/org/apache/isis/applib/adapters/DefaultsProvider.java
index 69a5fa5..cb51705 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/adapters/DefaultsProvider.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/adapters/DefaultsProvider.java
@@ -45,11 +45,15 @@ package org.apache.isis.applib.adapters;
  * @see EncoderDecoder
  * @see ValueSemanticsProvider
  */
+// tag::refguide[]
 public interface DefaultsProvider<T> {
 
+    // tag::refguide[]
     /**
      * The default, if any (as a pojo).
      */
     T getDefaultValue();
+    // tag::refguide[]
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/adapters/EncoderDecoder.java b/api/applib/src/main/java/org/apache/isis/applib/adapters/EncoderDecoder.java
index f15f195..ad2c792 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/adapters/EncoderDecoder.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/adapters/EncoderDecoder.java
@@ -45,8 +45,10 @@ package org.apache.isis.applib.adapters;
  * @see DefaultsProvider
  * @see ValueSemanticsProvider
  */
+// tag::refguide[]
 public interface EncoderDecoder<T> {
 
+    // end::refguide[]
     /**
      * Returns the provided object as an encoded string.
      *
@@ -56,16 +58,20 @@ public interface EncoderDecoder<T> {
      * constructor. That is, the object shouldn't encode itself, it should
      * encode the object provided to it.
      */
+    // tag::refguide[]
     String toEncodedString(T toEncode);
 
+    // end::refguide[]
     /**
      * Converts an encoded string to an instance of the object.
      *
      * <p>
      * Note that here the implementing class is acting as a factory for itself.
      *
-     * @see #toEncodedString(% toEncode)
+     * @see #toEncodedString(T toEncode)
      */
+    // tag::refguide[]
     T fromEncodedString(String encodedString);
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/adapters/EncodingException.java b/api/applib/src/main/java/org/apache/isis/applib/adapters/EncodingException.java
index 625d059..5827d0f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/adapters/EncodingException.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/adapters/EncodingException.java
@@ -22,6 +22,7 @@ package org.apache.isis.applib.adapters;
 /**
  * Indicates that encoding or decoding has failed.
  */
+// tag::refguide[]
 public class EncodingException extends RuntimeException {
     private static final long serialVersionUID = 1L;
 
@@ -42,3 +43,4 @@ public class EncodingException extends RuntimeException {
     }
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/adapters/Parser.java b/api/applib/src/main/java/org/apache/isis/applib/adapters/Parser.java
index 703441f..7cd592f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/adapters/Parser.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/adapters/Parser.java
@@ -74,8 +74,10 @@ package org.apache.isis.applib.adapters;
  * @see EncoderDecoder
  * @see ValueSemanticsProvider
  */
+// tag::refguide[]
 public interface Parser<T> {
 
+    // end::refguide[]
     /**
      * Parses a string to an instance of the object.
      *
@@ -85,23 +87,31 @@ public interface Parser<T> {
      *            - the context domain object for which the text is being
      *            parsed. For example +3 might mean add 3 to the current number.
      */
+    // tag::refguide[]
     T parseTextEntry(Object contextPojo, String entry);
 
+    // end::refguide[]
     /**
      * The typical length of objects that can be parsed.
      */
+    // tag::refguide[]
     int typicalLength();
 
+    // end::refguide[]
     /**
      * The title of the object.
      */
+    // tag::refguide[]
     String displayTitleOf(T object);
 
+    // end::refguide[]
     /**
      * The title of the object using a mask.
      */
+    // tag::refguide[]
     String displayTitleOf(T object, String usingMask);
 
+    // end::refguide[]
     /**
      * A title for the object that is valid but which may be easier to edit than
      * the title provided by a <code>TitleFacet</code>.
@@ -112,14 +122,18 @@ public interface Parser<T> {
      * field. So, a date might be rendered via a <code>TitleFacet</code> as
      * <tt>May 2, 2007</tt>, but its editable form might be <tt>20070502</tt>.
      */
+    // tag::refguide[]
     String parseableTitleOf(T existing);
 
+    // end::refguide[]
     /**
      * The max length of objects that can be parsed (if any).
      * A return type of -1 corresponds to unlimited.
      */
+    // tag::refguide[]
     default int maxLength() {
         return -1;
     }
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/adapters/ParsingException.java b/api/applib/src/main/java/org/apache/isis/applib/adapters/ParsingException.java
index a219eaf..9b4413e 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/adapters/ParsingException.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/adapters/ParsingException.java
@@ -23,6 +23,7 @@ package org.apache.isis.applib.adapters;
  * Indicates that parsing has failed, ie the entry is illegal (rather than
  * invalid).
  */
+// tag::refguide[]
 public class ParsingException extends RuntimeException {
     private static final long serialVersionUID = 1L;
 
@@ -43,3 +44,4 @@ public class ParsingException extends RuntimeException {
     }
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/adapters/ValueSemanticsProvider.java b/api/applib/src/main/java/org/apache/isis/applib/adapters/ValueSemanticsProvider.java
index 80c7336..a639ffd 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/adapters/ValueSemanticsProvider.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/adapters/ValueSemanticsProvider.java
@@ -39,24 +39,32 @@ import org.apache.isis.applib.annotation.Value;
  * @see EncoderDecoder
  * @see DefaultsProvider
  */
+// tag::refguide[]
 public interface ValueSemanticsProvider<T> {
 
+    // end::refguide[]
     /**
      * The {@link Parser}, if any.
      */
+    // tag::refguide[]
     Parser<T> getParser();
 
+    // end::refguide[]
     /**
      * The {@link EncoderDecoder}, if any.
      */
+    // tag::refguide[]
     EncoderDecoder<T> getEncoderDecoder();
 
+    // end::refguide[]
     /**
      * The {@link DefaultsProvider}, if any.
      *
      * <p>
      * If not <tt>null</tt>, implies that the value has (or may have) a default.
      */
+    // tag::refguide[]
     DefaultsProvider<T> getDefaultsProvider();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Action.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Action.java
index b9347b8..4549519 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Action.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Action.java
@@ -37,13 +37,18 @@ import org.apache.isis.applib.value.Clob;
 /**
  * Domain semantics for domain object collection.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.METHOD,
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE }
+)
 @Retention(RetentionPolicy.RUNTIME)
 @Mixin(method = "act")
 public @interface Action {
 
-
+    // end::refguide[]
     /**
      * Indicates that an invocation of the action should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -66,11 +71,10 @@ public @interface Action {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ActionDomainEvent<?>> domainEvent() default ActionDomainEvent.Default.class;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates where (in the UI) the action is not visible to the user.
      *
@@ -84,30 +88,34 @@ public @interface Action {
      *     {@link ActionLayout#contributed()}.
      * </p>
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The action semantics, either {@link SemanticsOf#SAFE_AND_REQUEST_CACHEABLE cached}, {@link SemanticsOf#SAFE safe} (query-only),
      * {@link SemanticsOf#IDEMPOTENT idempotent} or
      * {@link SemanticsOf#NON_IDEMPOTENT non-idempotent}.
      */
+    // tag::refguide[]
     SemanticsOf semantics() default SemanticsOf.NOT_SPECIFIED;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Whether the action invocation should be reified into a {@link org.apache.isis.applib.services.command.Command} object.
      */
+    // tag::refguide[]
     CommandReification command() default CommandReification.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * How the {@link org.apache.isis.applib.services.command.Command Command} object provided by the
      * {@link org.apache.isis.applib.services.command.CommandContext CommandContext} domain service should be persisted.
      */
+    // tag::refguide[]
     CommandPersistence commandPersistence() default CommandPersistence.PERSISTED;
 
+    // end::refguide[]
     /**
      * How the command/action should be executed.
      *
@@ -117,8 +125,10 @@ public @interface Action {
      * will be set to this value.
      * </p>
      */
+    // tag::refguide[]
     CommandExecuteIn commandExecuteIn() default CommandExecuteIn.FOREGROUND;
 
+    // end::refguide[]
     /**
      * The {@link CommandDtoProcessor} to process this command's DTO.
      *
@@ -133,12 +143,10 @@ public @interface Action {
      *     {@link ContentMappingServiceForCommandsDto} to dynamically transform the DTOs.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CommandDtoProcessor> commandDtoProcessor() default CommandDtoProcessor.class;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Whether the action invocation should be published.
      *
@@ -147,22 +155,18 @@ public @interface Action {
      * or {@link org.apache.isis.applib.services.publish.PublisherService} is registered with the framework.
      * </p>
      */
+    // tag::refguide[]
     Publishing publishing() default Publishing.NOT_SPECIFIED;
 
-
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The type-of the elements returned by the action.
      * @return
      */
+    // tag::refguide[]
     Class<?> typeOf() default Object.class;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Whether the action is restricted to prototyping.
      *
@@ -170,12 +174,10 @@ public @interface Action {
      *     By default there are no restrictions, with the action being available in all environments.
      * </p>
      */
+    // tag::refguide[]
     RestrictTo restrictTo() default RestrictTo.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Associates this action with a property or collection, specifying its id.
      *
@@ -195,8 +197,10 @@ public @interface Action {
      *     (in the Wicket UI, at least).
      * </p>
      */
+    // tag::refguide[]
     String associateWith() default "";
 
+    // end::refguide[]
     /**
      * Specifies the sequence/order in the UI for an action that's been associated with a property or collection.
      *
@@ -209,8 +213,10 @@ public @interface Action {
      *     For example <code>@Action(associateWith="items", associateWithSequence="2.1")</code>
      * </p>
      */
+    // tag::refguide[]
     String associateWithSequence() default "1";
 
+    // end::refguide[]
     /**
      * For uploading {@link Blob} or {@link Clob}, optionally restrict the files accepted (eg <tt>.xslx</tt>).
      *
@@ -220,5 +226,8 @@ public @interface Action {
      *
      * @see <a href="http://www.w3schools.com/tags/att_input_accept.asp">http://www.w3schools.com</a>
      */
+    // tag::refguide[]
     String fileAccept() default "";
-}
\ No newline at end of file
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/ActionLayout.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/ActionLayout.java
index ca1a3a7..8a6f370 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/ActionLayout.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/ActionLayout.java
@@ -32,13 +32,18 @@ import org.apache.isis.applib.layout.component.CssClassFaPosition;
 /**
  * Layout hints for actions.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.METHOD,
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Mixin(method = "act")
 public @interface ActionLayout {
 
-
+    // end::refguide[]
     /**
      * Whether (and how) this action can be bookmarked in the UI.
      *
@@ -48,10 +53,10 @@ public @interface ActionLayout {
      *     identically).
      * </p>
      */
+    // tag::refguide[]
     BookmarkPolicy bookmarking() default BookmarkPolicy.NOT_SPECIFIED;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates the css class that an action should have.
      *
@@ -59,47 +64,47 @@ public @interface ActionLayout {
      *     For the Wicket viewer, this can be a bootstrap class such as <code>btn-info</code>.
      * </p>
      */
+    // tag::refguide[]
     String cssClass() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a> CSS class to decorate an
      * action (button or menu item).
      */
+    // tag::refguide[]
     String cssClassFa() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates the position of the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a>
      * icon. The icon could be rendered on the left or the right of the action button
      */
+    // tag::refguide[]
     CssClassFaPosition cssClassFaPosition() default CssClassFaPosition.LEFT;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Description of this action, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates where in the UI the action should <i>not</i>not be visible.
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Name of this action (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * For actions that are associated with a property, indicates the positioning of the
      * action's button relative to the property.
@@ -108,6 +113,7 @@ public @interface ActionLayout {
      * Ignored if the action has not been associated with a property.
      * </p>
      */
+    // tag::refguide[]
     Position position() default Position.NOT_SPECIFIED;
 
     @XmlType(
@@ -121,22 +127,22 @@ public @interface ActionLayout {
         NOT_SPECIFIED
     }
 
+    // end::refguide[]
     /**
      * How this parameters for this action are prompted, either {@link PromptStyle#DIALOG dialog} or {@link PromptStyle#INLINE inline}.
      */
+    // tag::refguide[]
     PromptStyle promptStyle() default PromptStyle.AS_CONFIGURED;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * If the action returns its target, then determines whether to update the page or
      * instead to redirect (forcing a re-rendering of a new page).
      */
+    // tag::refguide[]
     Redirect redirectPolicy() default Redirect.AS_CONFIGURED;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * For actions of domain services that can be viewed and contributed (that is, whose
      * {@link DomainService#nature() nature} is either {@link org.apache.isis.applib.annotation.NatureOfService#VIEW}
@@ -147,7 +153,8 @@ public @interface ActionLayout {
      *     Has no meaning for actions of domain entities.
      * </p>
      */
+    // tag::refguide[]
     Contributed contributed() default Contributed.NOT_SPECIFIED;
 
-
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Auditing.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Auditing.java
index eb1f6f8..01fdf3c 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Auditing.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Auditing.java
@@ -21,7 +21,10 @@ package org.apache.isis.applib.annotation;
 /**
  * The available policies for auditing changes to the properties of the object.
  */
+// tag::refguide[]
 public enum Auditing {
+
+    // end::refguide[]
     /**
      * The auditing of the object should be as per the default auditing policy configured in <tt>application.properties</tt>.
      *
@@ -29,18 +32,30 @@ public enum Auditing {
      *     If no auditing policy is configured, then the auditing is disabled.
      * </p>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
+
+    // end::refguide[]
     /**
      * Audit changes to this object.
      */
+    // tag::refguide[]
     ENABLED,
+
+    // end::refguide[]
     /**
      * Do not audit changes to this object (even if otherwise configured to enable auditing).
      */
+    // tag::refguide[]
     DISABLED,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/BookmarkPolicy.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/BookmarkPolicy.java
index a310d85..a17a903 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/BookmarkPolicy.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/BookmarkPolicy.java
@@ -21,25 +21,40 @@ package org.apache.isis.applib.annotation;
 
 import javax.xml.bind.annotation.XmlType;
 
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum BookmarkPolicy {
+
+    // end::refguide[]
     /**
      * Can be bookmarked, and is a top-level 'root' (or parent) bookmark.
      */
+    // tag::refguide[]
     AS_ROOT,
+
+    // end::refguide[]
     /**
      * Can be bookmarked, but only as a child or some other parent/root bookmark
      */
+    // tag::refguide[]
     AS_CHILD,
+
+    // end::refguide[]
     /**
      * An unimportant entity that should never be bookmarked.
      */
+    // tag::refguide[]
     NEVER,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
-}
\ No newline at end of file
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Bounding.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Bounding.java
index fc33caa..4e18848 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Bounding.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Bounding.java
@@ -21,8 +21,10 @@ package org.apache.isis.applib.annotation;
 /**
  * Whether the set of instances of a domain object is bounded or not.
  */
+// tag::refguide[]
 public enum Bounding {
     BOUNDED,
     UNBOUNDED,
     NOT_SPECIFIED
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Collection.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Collection.java
index fa8944a..38a7d19 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Collection.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Collection.java
@@ -30,12 +30,19 @@ import org.apache.isis.applib.events.domain.CollectionDomainEvent;
 /**
  * Domain semantics for domain object collection.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.ANNOTATION_TYPE})
+@Target({
+        ElementType.METHOD,
+        ElementType.FIELD,
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Mixin(method = "coll")
 public @interface Collection {
 
+    // end::refguide[]
     /**
      * Indicates that changes to the collection that should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -56,18 +63,17 @@ public @interface Collection {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CollectionDomainEvent<?,?>> domainEvent() default CollectionDomainEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates when the collection is not visible to the user.
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Whether the properties of this domain object can be edited, or collections of this object be added to/removed from.
      *
@@ -75,36 +81,37 @@ public @interface Collection {
      *     Note that non-editable objects can nevertheless have actions invoked upon them.
      * </p>
      */
+    // tag::refguide[]
     Editing editing() default Editing.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * If {@link #editing()} is set to {@link Editing#DISABLED},
      * then the reason to provide to the user as to why this property cannot be edited.
      */
+    // tag::refguide[]
     String editingDisabledReason() default "";
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Indicates whether the collecion should be included or excluded from mementos.
      *
      * <p>
-     *     To ensure that the collection is actually not persisted in the objectstore, 
+     *     To ensure that the collection is actually not persisted in the objectstore,
      *     also annotate with the JDO annotation {@link javax.jdo.annotations.NotPersistent}.
      * </p>
      */
+    // tag::refguide[]
     MementoSerialization mementoSerialization() default MementoSerialization.NOT_SPECIFIED;
 
-
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The type-of the elements held within the collection.
+     *
      * @return
      */
+    // tag::refguide[]
     Class<?> typeOf() default Object.class;
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/CollectionLayout.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/CollectionLayout.java
index bc38db5..c061cbb 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/CollectionLayout.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/CollectionLayout.java
@@ -29,28 +29,33 @@ import java.util.Comparator;
 /**
  * Layout hints for collections.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.METHOD,
+        ElementType.FIELD,
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Mixin(method = "coll")
 public @interface CollectionLayout {
 
-
+    // end::refguide[]
     /**
      * Indicates the css class that a collection should have.
      */
+    // tag::refguide[]
     String cssClass() default "";
 
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Description of this collection, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates which view is used by default to render the collection.
      *
@@ -62,10 +67,10 @@ public @interface CollectionLayout {
      *     &quot;<a href="https://github.com/isisaddons/isis-wicket-gmap3">map</a>&quot;.
      * </p>
      */
+    // tag::refguide[]
     String defaultView() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates where in the UI the collection should <i>not</i>not be visible.
      *
@@ -74,24 +79,24 @@ public @interface CollectionLayout {
      *      apply for collections.
      * </p>
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Name of this collection (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * A flag indicating whether the value of {@linkplain #named()} should be HTML escaped or not.
      */
+    // tag::refguide[]
     boolean namedEscaped() default true;
 
+    // end::refguide[]
     /**
      * The page size for instances of this class when rendered within
      * a table.
@@ -104,13 +109,10 @@ public @interface CollectionLayout {
      * If annotated on a type, then the page size refers to standalone
      * collections (eg as returned from a repository query).
      */
+    // tag::refguide[]
     int paged() default -1;
 
-
-
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates that the elements in a ({@link java.util.SortedSet}) collection should be sorted according to a different order than the
      * natural sort order, as defined by the specified{@link java.util.Comparator}.
@@ -130,6 +132,8 @@ public @interface CollectionLayout {
      * may be sorted in an order more suitable to the context.
      */
     @SuppressWarnings("rawtypes")
+    // tag::refguide[]
     Class sortedBy() default Comparator.class;
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandExecuteIn.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandExecuteIn.java
index d416983..6aecd14 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandExecuteIn.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandExecuteIn.java
@@ -30,23 +30,24 @@ package org.apache.isis.applib.annotation;
  */
 // tag::refguide[]
 public enum CommandExecuteIn {
-// end::refguide[]
+
+    // end::refguide[]
     /**
      * Execute synchronously in the &quot;foreground&quot;, wait for the results.
      */
-// tag::refguide[]
+    // tag::refguide[]
     FOREGROUND,
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * Execute &quot;asynchronously&quot; through the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, returning (if possible) the
      * persisted {@link org.apache.isis.applib.services.command.Command command} object as a placeholder to the
      * result.
      */
-// tag::refguide[]
+    // tag::refguide[]
     BACKGROUND,
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * For commands that are replicated from a master onto a slave and are to be replayed (typically using the same
      * mechanism as "regular" background commands, eg a background job).
@@ -55,18 +56,19 @@ public enum CommandExecuteIn {
      *     For framework use, not intended to be used in application code.
      * </p>
      */
-// tag::refguide[]
+    // tag::refguide[]
     REPLAYABLE,
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * For commands that have been excluded and will not run.
      * These are typically for a replayable command that has hit an exception (which normally would prevent any further
      * replayable commands from being replayed) and which the administrator has decided to skip.
      */
-// tag::refguide[]
+    // tag::refguide[]
     EXCLUDED
-// end::refguide[]
+
+    // end::refguide[]
     ;
 
     public boolean isForeground() { return this == FOREGROUND; }
@@ -82,7 +84,7 @@ public enum CommandExecuteIn {
             private Meta() {}
         }
     }
+    // tag::refguide[]
 
-// tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandPersistence.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandPersistence.java
index b518f5a..635db744 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandPersistence.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandPersistence.java
@@ -23,34 +23,32 @@ package org.apache.isis.applib.annotation;
  */
 // tag::refguide[]
 public enum CommandPersistence {
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * (If the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
      * {@link org.apache.isis.applib.services.command.Command Command} object should be persisted.
      */
-// tag::refguide[]
+    // tag::refguide[]
     PERSISTED,
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * (If the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
      * {@link org.apache.isis.applib.services.command.Command Command} object should only be persisted if
      * another service, such as the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, hints that it should.
      */
-// tag::refguide[]
+    // tag::refguide[]
     IF_HINTED,
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * (Even if the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
      * {@link org.apache.isis.applib.services.command.Command Command} object should <i>not</i> be persisted (even if
      * another service, such as the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, hints that it should).
      */
-// tag::refguide[]
-    NOT_PERSISTED;
-// end::refguide[]
+    // tag::refguide[]
+    NOT_PERSISTED
 
-// tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandReification.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandReification.java
index 89edc33..32bef90 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandReification.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/CommandReification.java
@@ -21,7 +21,10 @@ package org.apache.isis.applib.annotation;
 /**
  * The available policies as to whether action invocations are reified into commands.
  */
+// tag::refguide[]
 public enum CommandReification {
+
+    // end::refguide[]
     /**
      * Whether the action should be handled as a command as per the default command configured in <tt>applicationp.properties</tt>.
      *
@@ -29,18 +32,30 @@ public enum CommandReification {
      *     If no command policy is configured, then the action is <i>not</i> treated as a command.
      * </p>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
+
+    // end::refguide[]
     /**
      * Handle the action as a command, irrespective of any configuration settings.
      */
+    // tag::refguide[]
     ENABLED,
+
+    // end::refguide[]
     /**
      * Do not handle the action as a command, irrespective of any configuration settings.
      */
+    // tag::refguide[]
     DISABLED,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Constants.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Constants.java
deleted file mode 100644
index c33615f..0000000
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Constants.java
+++ /dev/null
@@ -1,27 +0,0 @@
-/*
- *  Licensed to the Apache Software Foundation (ASF) under one
- *  or more contributor license agreements.  See the NOTICE file
- *  distributed with this work for additional information
- *  regarding copyright ownership.  The ASF licenses this file
- *  to you under the Apache License, Version 2.0 (the
- *  "License"); you may not use this file except in compliance
- *  with the License.  You may obtain a copy of the License at
- *
- *        http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing,
- *  software distributed under the License is distributed on an
- *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- *  KIND, either express or implied.  See the License for the
- *  specific language governing permissions and limitations
- *  under the License.
- */
-
-package org.apache.isis.applib.annotation;
-
-public class Constants {
-
-    private Constants(){}
-
-    public static final String MENU_ORDER_DEFAULT = "" + (Integer.MAX_VALUE - 100);
-}
\ No newline at end of file
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Contributed.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Contributed.java
index 64cb43c..8859a28 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Contributed.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Contributed.java
@@ -24,32 +24,50 @@ import javax.xml.bind.annotation.XmlType;
 /**
  * The means by which a domain service action will be contributed to a domain object.
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum Contributed {
+
+    // end::refguide[]
     /**
      * Default: contributed as both an action and also (if takes a single argument and has safe semantics) as an association
      * (contributed property if returns a single value, contributed collection if returns a collection).
      */
+    // tag::refguide[]
     AS_BOTH,
+
+    // end::refguide[]
     /**
      * Contributed as an action but <i>not</i> as an association.
      */
+    // tag::refguide[]
     AS_ACTION,
+
+    // end::refguide[]
     /**
      * (If takes a single argument and has safe semantics) then is contributed as an association
      * (contributed property if returns a single value, contributed collection if returns a collection) but <i>not</i>
      * as an action.
      */
+    // tag::refguide[]
     AS_ASSOCIATION,
+
+    // end::refguide[]
     /**
      * The action is not contributed as either an action or as an association.
      */
+    // tag::refguide[]
     AS_NEITHER,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
-}
\ No newline at end of file
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Defaulted.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Defaulted.java
index 3cc72fc..ad4bc6f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Defaulted.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Defaulted.java
@@ -48,11 +48,13 @@ import org.apache.isis.applib.adapters.DefaultsProvider;
  *     Note: This annotation is only incompletely recognized by the framework, and may be deprecated in the future.
  * </p>
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Defaulted {
 
+    // end::refguide[]
     /**
      * The fully qualified name of a class that implements the
      * {@link DefaultsProvider} interface.
@@ -66,8 +68,10 @@ public @interface Defaulted {
      * Implementation note: the default value provided here is simply an empty
      * string because <tt>null</tt> is not a valid default.
      */
+    // tag::refguide[]
     String defaultsProviderName() default "";
 
+    // end::refguide[]
     /**
      * As per {@link #defaultsProviderName()}, but specifying a class literal
      * rather than a fully qualified class name.
@@ -77,6 +81,8 @@ public @interface Defaulted {
      * {@link Defaulted}'s own class, because <tt>null</tt> is not a valid
      * default.
      */
+    // tag::refguide[]
     Class<?> defaultsProviderClass() default Defaulted.class;
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainObject.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainObject.java
index 785446f..bf5bee4 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainObject.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainObject.java
@@ -45,12 +45,17 @@ import org.apache.isis.applib.events.lifecycle.ObjectUpdatingEvent;
  * annotated type. 
  * For more details see <code>org.apache.isis.config.beans.IsisBeanFactoryPostProcessorForSpring</code>
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Component @Scope("prototype")
 public @interface DomainObject {
 
+    // end::refguide[]
     /**
      * Whether the entity should be audited (note: does not apply to view models or other recreatable objects.
      *
@@ -59,12 +64,10 @@ public @interface DomainObject {
      * registered with the framework.
      * </p>
      */
+    // tag::refguide[]
     Auditing auditing() default Auditing.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Whether changes to the object should be published.
      *
@@ -73,21 +76,20 @@ public @interface DomainObject {
      * registered with the framework.
      * </p>
      */
+    // tag::refguide[]
     Publishing publishing() default Publishing.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * The class of the domain service that provides an <code>autoComplete(String)</code> method.
      *
      * <p>
      * It is sufficient to specify an interface rather than a concrete type.
      */
+    // tag::refguide[]
     Class<?> autoCompleteRepository() default Object.class;
 
-
+    // end::refguide[]
     /**
      * The method (despite its name, not necessarily an action) to use in order to perform the auto-complete search
      * (defaults to &quot;autoComplete&quot;).
@@ -95,12 +97,10 @@ public @interface DomainObject {
      * <p>
      * The method is required to accept a single string parameter, and must return a list of the domain type.
      */
+    // tag::refguide[]
     String autoCompleteAction() default "autoComplete";
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Indicates that the class has a bounded, or finite, set of instances.
      *
@@ -113,12 +113,10 @@ public @interface DomainObject {
      * </p>
      *
      */
+    // tag::refguide[]
     Bounding bounding() default Bounding.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Whether the properties of this domain object can be edited, or collections of this object be added to/removed from.
      *
@@ -126,19 +124,18 @@ public @interface DomainObject {
      *     Note that non-editable objects can nevertheless have actions invoked upon them.
      * </p>
      */
+    // tag::refguide[]
     Editing editing() default Editing.NOT_SPECIFIED;
 
-
+    // end::refguide[]
     /**
      * If {@link #editing()} is set to {@link Editing#DISABLED},
      * then the reason to provide to the user as to why the object's properties cannot be edited/collections modified.
      */
+    // tag::refguide[]
     String editingDisabledReason() default "Disabled";
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Provides a unique abbreviation for the object type, eg &quot;customer.Customer&quot; for Customer.
      *
@@ -147,19 +144,17 @@ public @interface DomainObject {
      * used by the framework to unique identify an object over time (same concept as a URN).
      * </p>
      */
+    // tag::refguide[]
     String objectType() default "";
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * The nature of this domain object.
      */
+    // tag::refguide[]
     Nature nature() default Nature.NOT_SPECIFIED;
 
-
-
+    // end::refguide[]
     /**
      * Equivalent to {@link Mixin#method()}.
      *
@@ -167,11 +162,10 @@ public @interface DomainObject {
      *     Applicable only if {@link #nature()} is {@link Nature#MIXIN}.
      * </p>
      */
+    // tag::refguide[]
     String mixinMethod() default Mixin.DEFAULT_METHOD_NAME;
 
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -181,8 +175,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectCreatedEvent<?>> createdLifecycleEvent() default ObjectCreatedEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -192,8 +188,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectPersistingEvent<?>> persistingLifecycleEvent() default ObjectPersistingEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -203,8 +201,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectPersistedEvent<?>> persistedLifecycleEvent() default ObjectPersistedEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -214,8 +214,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectLoadedEvent<?>> loadedLifecycleEvent() default ObjectLoadedEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -225,8 +227,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectUpdatingEvent<?>> updatingLifecycleEvent() default ObjectUpdatingEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -236,9 +240,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectUpdatedEvent<?>> updatedLifecycleEvent() default ObjectUpdatedEvent.Default.class;
 
-
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -248,9 +253,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectRemovingEvent<?>> removingLifecycleEvent() default ObjectRemovingEvent.Default.class;
 
-
+    // end::refguide[]
     /**
      * Indicates that an invocation of <i>any</i> action of the domain object (that do not themselves specify their own
      * <tt>&#64;Action(domainEvent=...)</tt> should be posted to the
@@ -278,8 +284,10 @@ public @interface DomainObject {
      * It must also use <tt>Object</tt> as its generic type.  This is to allow mixins to also emit the same event.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ActionDomainEvent<?>> actionDomainEvent() default ActionDomainEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that changes to <i>any</i> property of the domain object (that do not themselves specify their own
      * <tt>&#64;Property(domainEvent=...)</tt> should be posted to the
@@ -302,8 +310,10 @@ public @interface DomainObject {
      * It must also use <tt>Object</tt> as its generic type.  This is to allow mixins to also emit the same event.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends PropertyDomainEvent<?,?>> propertyDomainEvent() default PropertyDomainEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that changes to <i>any</i> collection of the domain object (that do not themselves specify their own
      * <tt>&#64;Collection(domainEvent=...)</tt>  should be posted to the
@@ -325,6 +335,8 @@ public @interface DomainObject {
      * It must also use <tt>Object</tt> as its generic type.  This is to allow mixins to also emit the same event.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CollectionDomainEvent<?,?>> collectionDomainEvent() default CollectionDomainEvent.Default.class;
 
-}
\ No newline at end of file
+}
+// end::refguide[]
\ No newline at end of file
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainObjectLayout.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainObjectLayout.java
index 73344ce..b1360a8 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainObjectLayout.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainObjectLayout.java
@@ -34,12 +34,16 @@ import org.apache.isis.applib.layout.component.CssClassFaPosition;
 /**
  * Layout hints for domain objects.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface DomainObjectLayout {
 
-
+    // end::refguide[]
     /**
      * Which subclass of {@link TitleUiEvent} should be used to obtain a title.
      *
@@ -47,10 +51,10 @@ public @interface DomainObjectLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends TitleUiEvent<?>> titleUiEvent() default TitleUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link IconUiEvent} should be used to obtain an icon.
      *
@@ -58,10 +62,10 @@ public @interface DomainObjectLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends IconUiEvent<?>> iconUiEvent() default IconUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link CssClassUiEvent} should be used to obtain a CSS class.
      *
@@ -69,10 +73,10 @@ public @interface DomainObjectLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CssClassUiEvent<?>> cssClassUiEvent() default CssClassUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link LayoutUiEvent} should be used to obtain a layout.
      *
@@ -80,21 +84,25 @@ public @interface DomainObjectLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends LayoutUiEvent<?>> layoutUiEvent() default LayoutUiEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates the css class that a domain class (type) should have.
      */
+    // tag::refguide[]
     String cssClass() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a> CSS class to decorate an
      * domain object.
      */
+    // tag::refguide[]
     String cssClassFa() default "";
 
+    // end::refguide[]
     /**
      * Indicates the position of the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a>
      * icon. The icon could be rendered on the left or the right of the object's title.
@@ -103,27 +111,24 @@ public @interface DomainObjectLayout {
      *     This attribute is currently ignored by Isis viewers.
      * </p>
      */
+    // tag::refguide[]
     CssClassFaPosition cssClassFaPosition() default CssClassFaPosition.LEFT;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Description of this class, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Name of this class (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The page size for instances of this class when rendered within
      * a table.
@@ -136,21 +141,22 @@ public @interface DomainObjectLayout {
      * If annotated on a type, then the page size refers to standalone
      * collections (eg as returned from a repository query).
      */
+    // tag::refguide[]
     int paged() default -1;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The plural name of the class.
      */
+    // tag::refguide[]
     String plural() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Whether (and how) this domain object can be bookmarked in the UI.
      */
+    // tag::refguide[]
     BookmarkPolicy bookmarking() default BookmarkPolicy.NOT_SPECIFIED;
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainService.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainService.java
index e836635..02b2cee 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainService.java
@@ -41,21 +41,34 @@ import org.springframework.stereotype.Service;
  * For more details see {@link org.apache.isis.config.beans.IsisBeanFactoryPostProcessorForSpring}.
  * 
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Service @Singleton
 public @interface DomainService {
 
+    // end::refguide[]
     /**
      * Provides the (first part of the) unique identifier (OID) for the service (the instanceId is always &quot;1&quot;).
      *
      * <p>
      * If not specified then either the optional &quot;getId()&quot is used, otherwise the class' name.
      */
+    // tag::refguide[]
     String objectType() default "";
 
+    // end::refguide[]
+    /**
+     * The nature of this service, eg for menus, contributed actions, repository.
+     */
+    // tag::refguide[]
+    NatureOfService nature() default NatureOfService.VIEW;
 
+    // end::refguide[]
     /**
      * If this domain service acts as a repository for an entity type, specify that entity type.
      * @deprecated was never implemented
@@ -63,10 +76,6 @@ public @interface DomainService {
     @Deprecated
     Class<?> repositoryFor() default Object.class;
 
-    /**
-     * The nature of this service, eg for menus, contributed actions, repository.
-     */
-    NatureOfService nature() default NatureOfService.VIEW;
-
-
+    // tag::refguide[]
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainServiceLayout.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainServiceLayout.java
index abc7fc1..a3342fe 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainServiceLayout.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/DomainServiceLayout.java
@@ -32,14 +32,20 @@ import java.lang.annotation.Target;
  * Also indicates the name, and menu ordering UI hints.
  * </p>
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface DomainServiceLayout {
 
+    // end::refguide[]
     /**
      * Name of this class (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
     public enum MenuBar {
@@ -49,12 +55,15 @@ public @interface DomainServiceLayout {
         NOT_SPECIFIED
     }
 
+    // end::refguide[]
     /**
      * The menubar in which the menu that holds this service's actions should reside.
      */
+    // tag::refguide[]
     MenuBar menuBar() default MenuBar.NOT_SPECIFIED;
 
-    //TODO[2140] DomainServiceLayout 
+    // end::refguide[]
+    //TODO[2140] DomainServiceLayout
     //    /**
     //     * Number in Dewey Decimal format representing the order.
     //     *
@@ -78,4 +87,8 @@ public @interface DomainServiceLayout {
     //     * </p>
     //     */
     //    String menuOrder() default Constants.MENU_ORDER_DEFAULT;
+
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Editing.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Editing.java
index 9404bc4..32c1761 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Editing.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Editing.java
@@ -21,7 +21,10 @@ package org.apache.isis.applib.annotation;
 /**
  * The available policies for editing properties and collections.
  */
+// tag::refguide[]
 public enum Editing {
+
+    // end::refguide[]
     /**
      * The editing of the object should be as per the default editing policy configured in <tt>application.properties</tt>.
      *
@@ -29,19 +32,30 @@ public enum Editing {
      *     If no editing policy is configured, then the editing is enabled.
      * </p>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
+
+    // end::refguide[]
     /**
      * Audit changes to this object.
      */
+    // tag::refguide[]
     ENABLED,
+
+    // end::refguide[]
     /**
      * Do not allow the properties to be edited, or the collections to be added to/removed from.
      */
+    // tag::refguide[]
     DISABLED,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/EqualByContent.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/EqualByContent.java
index afaf0ad..b907f48 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/EqualByContent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/EqualByContent.java
@@ -57,8 +57,13 @@ import java.util.HashMap;
  *     Note: This annotation is only incompletely recognized by the framework, and may be deprecated in the future.
  * </p>
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.METHOD })
+@Target({
+        ElementType.TYPE,
+        ElementType.METHOD
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface EqualByContent {
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Facets.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Facets.java
index db68ad0..8be974f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Facets.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Facets.java
@@ -33,10 +33,13 @@ import java.lang.annotation.Target;
  * At least one named factory (as per {@link #facetFactoryNames()}) or one class
  * factory (as per {@link #facetFactoryClasses()}) should be specified.
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Facets {
+
+    // end::refguide[]
     /**
      * Array of fully qualified names of classes each implementing
      * <tt>org.apache.isis.core.metamodel.facets.FacetFactory</tt>.
@@ -45,8 +48,10 @@ public @interface Facets {
      * Either the array provided by this method or by
      * {@link #facetFactoryClasses()} should be non-empty.
      */
+    // tag::refguide[]
     String[] facetFactoryNames() default {};
 
+    // end::refguide[]
     /**
      * Array of {@link Class}s, each indicating a class implementing
      * <tt>org.apache.isis.core.metamodel.facets.FacetFactory</tt>.
@@ -55,6 +60,8 @@ public @interface Facets {
      * Either the array provided by this method or by
      * {@link #facetFactoryNames()} should be non-empty.
      */
+    // tag::refguide[]
     Class<?>[] facetFactoryClasses() default {};
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/HomePage.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/HomePage.java
index fbc757f..014f8e5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/HomePage.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/HomePage.java
@@ -34,8 +34,10 @@ import java.lang.annotation.Target;
  *     to traverse or operate on the rendered state.
  * </p>
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface HomePage {
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/LabelPosition.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/LabelPosition.java
index 99abea8..5ac5aa1 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/LabelPosition.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/LabelPosition.java
@@ -26,23 +26,30 @@ import javax.xml.bind.annotation.XmlType;
  * @see org.apache.isis.applib.annotation.PropertyLayout
  * @see org.apache.isis.applib.annotation.ParameterLayout
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum LabelPosition {
+
     DEFAULT,
     LEFT,
-
+    // end::refguide[]
     /**
      * Right position of the label for Boolean properties.
      * <strong>Not supported</strong> for now for other types.
      */
+    // tag::refguide[]
     RIGHT,
     TOP,
     NONE,
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/MemberOrder.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/MemberOrder.java
index 659f1a2..eef7938 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/MemberOrder.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/MemberOrder.java
@@ -33,11 +33,13 @@ import java.lang.annotation.Target;
  *     where <code>Xxx</code> is the domain object name.
  * </p>
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.METHOD, ElementType.FIELD })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface MemberOrder {
 
+    // end::refguide[]
     /**
      * Groups or associate members with each other.
      *
@@ -47,13 +49,17 @@ public @interface MemberOrder {
      *     <li>For collections, currently has no meaning</li>
      * </ul>
      */
+    // tag::refguide[]
     String name() default "";
 
+    // end::refguide[]
     /**
      * The order of this member relative to other members in the same group, in
      * Dewey-decimal notation.  For collections this is relative to each other
      * (collections aren't grouped).
      */
+    // tag::refguide[]
     String sequence();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/MementoSerialization.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/MementoSerialization.java
index 9f79818..a4f9410 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/MementoSerialization.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/MementoSerialization.java
@@ -21,12 +21,18 @@ package org.apache.isis.applib.annotation;
 /**
  * Whether the property or collection is included if the domain object is serialized into a memento.
  */
+// tag::refguide[]
 public enum MementoSerialization {
+
+    // end::refguide[]
     /**
      * Property or collection is included in any mementos.
      * This is the fallback/default if not explicitly excluded.
      */
+    // tag::refguide[]
     INCLUDED,
+
+    // end::refguide[]
     /**
      * Property or collection's state is excluded from any mementos.
      *
@@ -34,10 +40,16 @@ public enum MementoSerialization {
      *     Corresponds to <tt>@Property(notPersisted=true)</tt> or <tt>@Collection(notPersisted=true)</tt> prior to Isis 2.x
      * </p>
      */
+    // tag::refguide[]
     EXCLUDED,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/MinLength.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/MinLength.java
index 77bba48..469a0e3 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/MinLength.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/MinLength.java
@@ -28,10 +28,11 @@ import java.lang.annotation.Target;
 /**
  * Specify the minimum number of characters for an autocomplete search argument.
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.PARAMETER })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface MinLength {
-
     int value();
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Mixin.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Mixin.java
index 5e47907..5d8d41c 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Mixin.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Mixin.java
@@ -36,17 +36,21 @@ import org.springframework.stereotype.Component;
  * annotated type. 
  * For more details see {@link org.apache.isis.config.beans.IsisBeanFactoryPostProcessorForSpring}.
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 @Component @Scope("prototype")
 public @interface Mixin {
 
+    // end::refguide[]
     /**
      * The default of {@link Mixin#method()}).
      */
+    // tag::refguide[]
     String DEFAULT_METHOD_NAME = "$$";
 
+    // end::refguide[]
     /**
      * Specifies the name of the verb to use within the mixin, eg "exec", "invoke", "apply" and so on,
      *
@@ -64,6 +68,8 @@ public @interface Mixin {
      *     valid identifiers after Java 8.
      * </p>
      */
+    // tag::refguide[]
     String method() default DEFAULT_METHOD_NAME;
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Module.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Module.java
index 7b7887f..b9e82b3 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Module.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Module.java
@@ -49,6 +49,7 @@ import org.springframework.context.annotation.Import;
  *             scanning more classes than are needed.  It is therefore not used within the framework code, but is
  *             provided as a convenience by domain applications.
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
@@ -56,5 +57,5 @@ import org.springframework.context.annotation.Import;
 @Documented
 @ComponentScan
 public @interface Module {
-
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Nature.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Nature.java
index df64918..b044747 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Nature.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Nature.java
@@ -28,15 +28,19 @@ import javax.xml.bind.annotation.XmlRootElement;
  *     difference is one of intent.
  * </p>
  */
+// tag::refguide[]
 public enum Nature {
 
+    // end::refguide[]
     /**
      * The default; allows the programmer to combine <tt>@DomainObject</tt> annotation with the
      * {@link ViewModel} annotation, or the {@link XmlRootElement} annotation, or by implementing the
      * {@link org.apache.isis.applib.ViewModel} interface.
      */
+    // tag::refguide[]
     NOT_SPECIFIED,
 
+    // end::refguide[]
     /**
      * A domain entity whose persistence is managed internally by Isis, using JDO as the persistence implementation.
      * Domain entities are considered to be part of the domain model layer.
@@ -49,7 +53,10 @@ public enum Nature {
      *    Currently implies no additional semantics other than documentation.
      * </p>
      */
+    // tag::refguide[]
     JDO_ENTITY,
+
+    // end::refguide[]
     /**
      * A domain entity that is a wrapper/proxy/stub to some externally managed entity.  Domain entities are
      * considered to be part of the domain model layer.
@@ -64,15 +71,18 @@ public enum Nature {
      *     {@link XmlRootElement} annotation instead.
      * </p>
      */
+    // tag::refguide[]
     EXTERNAL_ENTITY,
+
+    // end::refguide[]
     /**
      * A domain entity that is a wrapper/proxy/stub to a &quot;synthetic&quot; entity, for example one that is
      * constructed from some sort of internal memory data structure.
      *
      * <p>
-     *     As for a {@link #EXTERNAL_ENTITY}, the identity of a synthetic entity is determined solely by the 
+     *     As for a {@link #EXTERNAL_ENTITY}, the identity of a synthetic entity is determined solely by the
      *     state of object's properties (that have not been set to be ignored using
-     *     {@link org.apache.isis.applib.annotation.Property#notPersisted()}).
+     *     {@link Property#mementoSerialization()}).
      * </p>
      *
      * <p>
@@ -80,7 +90,10 @@ public enum Nature {
      *     {@link XmlRootElement} annotation instead.
      * </p>
      */
+    // tag::refguide[]
     INMEMORY_ENTITY,
+
+    // end::refguide[]
     /**
      * An object that is conceptually part of the application layer, and which surfaces behavior and/or state that
      * is aggregate of one or more domain entity.
@@ -100,20 +113,26 @@ public enum Nature {
      *
      * @see ViewModel
      */
+    // tag::refguide[]
     VIEW_MODEL,
 
+    // end::refguide[]
     /**
      * An object that acts as a mix-in to some other object, contributing behavior and/or derived state based on the
      * domain object.
      *
      * @see Mixin
      */
+    // tag::refguide[]
     MIXIN,
-    
+
+    // end::refguide[]
     /**
-     * An object that is entirely managed by the underlying IoC container. 
+     * An object that is entirely managed by the underlying IoC container.
      * @apiNote EXPERIMENTAL
      */
+    // tag::refguide[]
     BEAN,
-    
+
 }
+// tag::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/NatureOfService.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/NatureOfService.java
index f02c2aa..77ad2d9 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/NatureOfService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/NatureOfService.java
@@ -22,23 +22,32 @@ package org.apache.isis.applib.annotation;
  * The different sorts of domain services recognized by Isis, as specified in {@link DomainService#nature()}
  * 
  */
+// tag::refguide[]
 public enum NatureOfService {
 
+    // end::refguide[]
     /**
      * The service's actions appear in the REST API and in 'viewers', eg. in the menu bar.
-     * 
+     *
      * @apiNote
      * Contributing actions to the 'viewer' implies, that these must also be exposed to the REST API,
-     * simply because alternative viewers might be solely based on the provided REST end-points.  
+     * simply because alternative viewers might be solely based on the provided REST end-points.
      */
+    // tag::refguide[]
     VIEW,
 
+    // end::refguide[]
     /**
      * The service's actions should only be visible in the REST API exposed by the Restful Objects viewer.
      */
+    // tag::refguide[]
     REST,
-    
+
+    // end::refguide[]
+
+    //
     // -- DEPRECATIONS
+    //
 
     /**
      * A <em>programmatic</em> service.
@@ -59,21 +68,21 @@ public enum NatureOfService {
      */
     @Deprecated
     VIEW_REST_ONLY,
-    
+
     /**
      * @deprecated will be removed with 2.0.0 release! use {@link #VIEW} instead
      * @apiNote For now, used as synonym for {@link #VIEW}
      */
     @Deprecated
     VIEW_MENU_ONLY,
-    
+
     /**
      * @deprecated will be removed with 2.0.0 release!
      * <p>
-     * For now, contributing actions will be gathered to show up in the 'others' menu to ease migration. 
+     * For now, contributing actions will be gathered to show up in the 'others' menu to ease migration.
      * These will likely not work.
      * <p>
-     * Migration Note: For each {@code Action} write a new mixin class. 
+     * Migration Note: For each {@code Action} write a new mixin class.
      * see {@link Mixin}
      * @apiNote For now, used as synonym for {@link #VIEW}
      */
@@ -90,7 +99,7 @@ public enum NatureOfService {
     public boolean isView() {
         return this == VIEW || this == VIEW_MENU_ONLY  || this == VIEW_CONTRIBUTIONS_ONLY;
     }
-    
+
     /**
      * Whether a service contributes its actions exclusively to the REST API.
      * @see {@link NatureOfService#REST}
@@ -98,7 +107,7 @@ public enum NatureOfService {
     public boolean isRestOnly() {
         return this == REST || this == VIEW_REST_ONLY;
     }
-    
+
     /**
      * Whether a service contributes no actions at all.
      * @see {@link NatureOfService#DOMAIN}
@@ -116,7 +125,7 @@ public enum NatureOfService {
         return isRestOnly() || isView();
     }
 
-
-
+    // tag::refguide[]
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Navigable.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Navigable.java
index 6daac44..d4ba91e 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Navigable.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Navigable.java
@@ -26,19 +26,20 @@ package org.apache.isis.applib.annotation;
  * @since 2.0
  *
  */
+// tag::refguide[]
 public enum Navigable {
 
-
     NOT_SPECIFIED,
-
     IGNORE,
-
     PARENT,
-
+    // end::refguide[]
     ;
 
     public boolean isParent() {
         return this == PARENT;
     }
 
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Optionality.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Optionality.java
index e3efad5..9389e42 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Optionality.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Optionality.java
@@ -21,30 +21,39 @@ package org.apache.isis.applib.annotation;
 /**
  * Whether the property or parameter is optional or is required (aka mandatory).
  */
+// tag::refguide[]
 public enum Optionality {
+
+    // end::refguide[]
     /**
      * Default, usually meaning mandatory for properties and always meaning mandatory for parameters.
      *
      * <p>
-     * For properties, will be false unless JDO {@link javax.jdo.annotations.Column} has also specified with
-     * {@link javax.jdo.annotations.Column#allowsNull()} set to <code>true</code>.
+     * For properties, will be false unless JDO <code>javax.jdo.annotations.Column</code> has also specified with
+     * <code>javax.jdo.annotations.Column#allowsNull()</code> set to <code>true</code>.
      * </p>
      */
+    // tag::refguide[]
     DEFAULT,
+
+    // end::refguide[]
     /**
      * Indicates that the property or parameter is not required.
      */
+    // tag::refguide[]
     OPTIONAL,
+
+    // end::refguide[]
     /**
-     * Indicates that the property is required (even if the JDO {@link javax.jdo.annotations.Column} annotation
+     * Indicates that the property is required (even if the JDO <code>javax.jdo.annotations.Column</code> annotation
      * says otherwise).
      *
      * <p>
      * When using the JDO/DataNucleus objectstore, it is sometimes necessary to annotate a property as optional
-     * (using {@link javax.jdo.annotations.Column#allowsNull()} set to <code>true</code>), even if the property is
+     * (using <code>javax.jdo.annotations.Column#allowsNull()</code> set to <code>true</code>), even if the property is
      * logically mandatory.  For example, this can occur when the property is in a subtype class that has been
-     * "rolled up" to the superclass table using {@link javax.jdo.annotations.Inheritance} with the
-     * {@link javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE superclass}<tt> strategy.
+     * "rolled up" to the superclass table using <code>javax.jdo.annotations.Inheritance</code>> with the
+     * <code>javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE</code> superclass strategy.
      * </p>
      *
      * <p>
@@ -53,10 +62,16 @@ public enum Optionality {
      * is unable to do so.
      * </p>
      */
+    // tag::refguide[]
     MANDATORY,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/OrderPrecedence.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/OrderPrecedence.java
index 7751a58..e4caea8 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/OrderPrecedence.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/OrderPrecedence.java
@@ -27,6 +27,7 @@ import lombok.experimental.UtilityClass;
 @UtilityClass
 public class OrderPrecedence {
 
+    // end::refguide[]
     /**
      * For domain services with the highest precedence value.
      * No framework services use this constant, but some very fundamental services (eg for security)
@@ -35,28 +36,40 @@ public class OrderPrecedence {
      * @see java.lang.Integer#MIN_VALUE
      * @see Ordered#HIGHEST_PRECEDENCE
      */
+    // tag::refguide[]
     public static final int FIRST = Ordered.HIGHEST_PRECEDENCE;
 
+    // end::refguide[]
     /**
      * For framework for services that are unlikely to be overridden by application code.
      */
+    // tag::refguide[]
     public static final int EARLY = FIRST / 2;
+
+    // end::refguide[]
     /**
      * For framework for services that could be overridden by application code (though not commonly).
      */
+    // tag::refguide[]
     public static final int MIDPOINT = 0;
+
+    // end::refguide[]
     /**
      * For framework services that are expected to be overridden by application code, or that act as a fallback.
      */
+    // tag::refguide[]
     public static final int LATE = OrderPrecedence.LAST / 2;
 
+    // end::refguide[]
     /**
      * For domain services that act as a fallback, and which will typically be overridden.
      *
      * @see java.lang.Integer#MAX_VALUE
      * @see Ordered#LOWEST_PRECEDENCE
      */
+    // tag::refguide[]
     public static final int LAST = Ordered.LOWEST_PRECEDENCE;
 
 }
 // end::refguide[]
+
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Parameter.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Parameter.java
index 718908c..149a336 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Parameter.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Parameter.java
@@ -32,13 +32,16 @@ import org.apache.isis.applib.value.Clob;
 /**
  * Domain semantics for domain object collection.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.PARAMETER, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.PARAMETER,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Parameter {
 
-
-
+    // end::refguide[]
     /**
      * The maximum entry length of a field.
      *
@@ -46,10 +49,10 @@ public @interface Parameter {
      *     The default value (<code>-1</code>) indicates that no maxLength has been specified.
      * </p>
      */
+    // tag::refguide[]
     int maxLength() default -1;
 
-
-
+    // end::refguide[]
     /**
      * Whether this parameter is optional or is mandatory (ie required).
      *
@@ -58,10 +61,10 @@ public @interface Parameter {
      *     to mean that the parameter is required.
      * </p>
      */
+    // tag::refguide[]
     Optionality optionality() default Optionality.NOT_SPECIFIED;
 
-
-
+    // end::refguide[]
     /**
      * The {@link org.apache.isis.applib.spec.Specification}(s) to be satisfied by this parameter.
      *
@@ -69,15 +72,17 @@ public @interface Parameter {
      * If more than one is provided, then all must be satisfied (in effect &quot;AND&quot;ed together).
      * </p>
      */
+    // tag::refguide[]
     Class<? extends Specification>[] mustSatisfy() default {};
 
-
-
+    // end::refguide[]
     /**
      * Regular expression pattern that a value should conform to, and can be formatted as.
      */
+    // tag::refguide[]
     String regexPattern() default "";
 
+    // end::refguide[]
     /**
      * Pattern flags, as per {@link java.util.regex.Pattern#compile(String, int)} .
      *
@@ -85,14 +90,17 @@ public @interface Parameter {
      *     The default value, <code>0</code>, means that no flags have been specified.
      * </p>
      */
+    // tag::refguide[]
     int regexPatternFlags() default 0;
 
+    // end::refguide[]
     /**
      * Replacement text for the pattern in generated error message.
      */
+    // tag::refguide[]
     String regexPatternReplacement() default "Doesn't match pattern";
 
-
+    // end::refguide[]
     /**
      * For uploading {@link Blob} or {@link Clob}, optionally restrict the files accepted (eg <tt>.xslx</tt>).
      *
@@ -102,6 +110,8 @@ public @interface Parameter {
      *
      * @see <a href="http://www.w3schools.com/tags/att_input_accept.asp">http://www.w3schools.com</a>
      */
+    // tag::refguide[]
     String fileAccept() default "";
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/ParameterLayout.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/ParameterLayout.java
index 60bf10c..782b3a6 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/ParameterLayout.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/ParameterLayout.java
@@ -30,21 +30,30 @@ import java.lang.annotation.Target;
  *
  * @see org.apache.isis.applib.annotation.PropertyLayout
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.PARAMETER, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.PARAMETER,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ParameterLayout {
 
+    // end::refguide[]
     /**
      * Indicates the css class that a parameter should have.
      */
+    // tag::refguide[]
     String cssClass() default "";
 
+    // end::refguide[]
     /**
      * Description of this property, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
+    // end::refguide[]
     /**
      * In forms, positioning of the label (left, top or none) relative to the parameter value.
      *
@@ -52,23 +61,31 @@ public @interface ParameterLayout {
      * If not specified, the default depends upon the parameter value's datatype.
      * </p>
      */
+    // tag::refguide[]
     LabelPosition labelPosition() default LabelPosition.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * Name of this action parameter.
      */
+    // tag::refguide[]
     String named() default "";
 
+    // end::refguide[]
     /**
      * A flag indicating whether the value of {@linkplain #named()} should be HTML escaped or not.
      */
+    // tag::refguide[]
     boolean namedEscaped() default true;
 
+    // end::refguide[]
     /**
      * For string parameters (and properties), whether to render as a text area over multiple lines.
      */
+    // tag::refguide[]
     int multiLine() default -1;
 
+    // end::refguide[]
     /**
      * For date parameters (and properties) only, instructs the viewer that the date should be rendered as one day
      * prior to the actually stored date.
@@ -93,12 +110,15 @@ public @interface ParameterLayout {
      * In the domain object, itself, however, the value stored is 1-jun-2013.
      * </p>
      */
+    // tag::refguide[]
     RenderDay renderDay() default RenderDay.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * The typical entry length of a field, use to determine the optimum width for display
      */
+    // tag::refguide[]
     int typicalLength() default -1;
 
 }
-
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Programmatic.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Programmatic.java
index ce61dc7..215bf43 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Programmatic.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Programmatic.java
@@ -38,14 +38,15 @@ import java.lang.annotation.Target;
  * It can also be added to a type, meaning that the type is ignored from the metamodel.
  * This is intended as a &quot;get out of jail&quot; for any classes from unit tests, say,
  * that end up on the classpath of integration tests but should otherwise be ignored.
- *
- * <p>
- * This is intended as a replacement for {@link Ignore} (the use of which is
- * being discouraged because of the name clash with <tt>org.junit.Ignore</tt>).
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
+@Target({
+        ElementType.METHOD,
+        ElementType.TYPE,
+        ElementType.FIELD
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Programmatic {
-
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Projecting.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Projecting.java
index ce231ce..82b7a74 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Projecting.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Projecting.java
@@ -18,14 +18,22 @@
  */
 package org.apache.isis.applib.annotation;
 
+// tag::refguide[]
 public enum Projecting {
 
+    // end::refguide[]
     /**
      * The property holds the underlying domain object of which this (view model) object is a projection.
      */
+    // tag::refguide[]
     PROJECTED,
+
+    // end::refguide[]
     /**
      * The property
      */
+    // tag::refguide[]
     NOT_SPECIFIED;
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/PromptStyle.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/PromptStyle.java
index 2c6d6da..bbe9e1b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/PromptStyle.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/PromptStyle.java
@@ -23,10 +23,13 @@ import javax.xml.bind.annotation.XmlType;
 /**
  * How prompting for new values of a property/arguments for an action should be performed
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum PromptStyle {
+
+    // end::refguide[]
     /**
      * Prompt using the style configured by <tt>isis.viewer.wicket.promptStyle</tt>.
      *
@@ -34,7 +37,10 @@ public enum PromptStyle {
      *      If no style is configured, then {@link #INLINE} is assumed.
      * </p>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
+
+    // end::refguide[]
     /**
      * Use a dialog for the prompt.
      *
@@ -44,19 +50,31 @@ public enum PromptStyle {
      *     <code>isis.viweer.wicket.dialogMode</code> configuration property.
      * </p>
      */
+    // tag::refguide[]
     DIALOG,
+
+    // end::refguide[]
     /**
      * Use a dialog for the prompt, rendered in a sidebar.
      */
+    // tag::refguide[]
     DIALOG_SIDEBAR,
+
+    // end::refguide[]
     /**
      * Use a dialog for the prompt, rendered in a modal dialog.
      */
+    // tag::refguide[]
     DIALOG_MODAL,
+
+    // end::refguide[]
     /**
      * Show the form inline, temporarily replacing the rendering of the property.
      */
+    // tag::refguide[]
     INLINE,
+
+    // end::refguide[]
     /**
      * Applies only to actions, show the form inline, invoked as if editing the property.
      *
@@ -76,16 +94,23 @@ public enum PromptStyle {
      * </p>
      *
      */
+    // tag::refguide[]
     INLINE_AS_IF_EDIT,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED;
 
+    // end::refguide[]
     public boolean isDialog() { return this == DIALOG || this == DIALOG_MODAL || this == DIALOG_SIDEBAR; }
     public boolean isInline() { return this == INLINE; }
     public boolean isInlineAsIfEdit() { return this == INLINE_AS_IF_EDIT; }
-
     public boolean isInlineOrInlineAsIfEdit() { return this == INLINE || this == INLINE_AS_IF_EDIT; }
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Property.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Property.java
index bd774db..df31640 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Property.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Property.java
@@ -38,15 +38,19 @@ import org.apache.isis.applib.value.Clob;
 /**
  * Domain semantics for domain object property.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.METHOD,
+        ElementType.FIELD,
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
-
-//@Action(semantics=SemanticsOf.SAFE)   
-//@ActionLayout(contributed=Contributed.AS_ASSOCIATION)
 @Mixin(method = "prop")
 public @interface Property {
 
+    // end::refguide[]
     /**
      * Indicates that changes to the property that should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -66,17 +70,17 @@ public @interface Property {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends PropertyDomainEvent<?,?>> domainEvent() default PropertyDomainEvent.Default.class;
 
-
-
-
-
+    // end::refguide[]
     /**
      * Indicates where the property is not visible to the user.
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * If set to {@link Projecting#PROJECTED projected}, then indicates that the owner of this property is a view model
      * which is a projection of some other entity, and that the property holds a reference to that
@@ -91,11 +95,10 @@ public @interface Property {
      *     Only one such property should be marked as being a projection with a view model.
      * </p>
      */
+    // tag::refguide[]
     Projecting projecting() default Projecting.NOT_SPECIFIED;
 
-
-
-
+    // end::refguide[]
     /**
      * Whether the properties of this domain object can be edited, or collections of this object be added to/removed from.
      *
@@ -103,29 +106,32 @@ public @interface Property {
      *     Note that non-editable objects can nevertheless have actions invoked upon them.
      * </p>
      */
+    // tag::refguide[]
     Editing editing() default Editing.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * If {@link #editing()} is set to {@link Editing#DISABLED},
      * then the reason to provide to the user as to why this property cannot be edited.
      */
+    // tag::refguide[]
     String editingDisabledReason() default "";
 
-
-
-
-
+    // end::refguide[]
     /**
      * Whether the property edit should be reified into a {@link org.apache.isis.applib.services.command.Command} object.
      */
     CommandReification command() default CommandReification.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * How the {@link org.apache.isis.applib.services.command.Command Command} object provided by the
      * {@link org.apache.isis.applib.services.command.CommandContext CommandContext} domain service should be persisted.
      */
+    // tag::refguide[]
     CommandPersistence commandPersistence() default CommandPersistence.PERSISTED;
 
+    // end::refguide[]
     /**
      * How the command/property edit should be executed.
      *
@@ -135,10 +141,10 @@ public @interface Property {
      * will be set to this value.
      * </p>
      */
+    // tag::refguide[]
     CommandExecuteIn commandExecuteIn() default CommandExecuteIn.FOREGROUND;
 
-
-
+    // end::refguide[]
     /**
      * Whether the property edit should be published.
      *
@@ -147,9 +153,10 @@ public @interface Property {
      * or {@link org.apache.isis.applib.services.publish.PublisherService} is registered with the framework.
      * </p>
      */
+    // tag::refguide[]
     Publishing publishing() default Publishing.NOT_SPECIFIED;
 
-
+    // end::refguide[]
     /**
      * The {@link CommandDtoProcessor} to process this command's DTO.
      *
@@ -164,11 +171,10 @@ public @interface Property {
      *     {@link ContentMappingServiceForCommandsDto} to dynamically transform the DTOs.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CommandDtoProcessor> commandDtoProcessor() default CommandDtoProcessor.class;
 
-
-
-
+    // end::refguide[]
     /**
      * The maximum entry length of a field.
      *
@@ -176,12 +182,10 @@ public @interface Property {
      *     The default value (<code>-1</code>) indicates that no maxLength has been specified.
      * </p>
      */
+    // tag::refguide[]
     int maxLength() default -1;
 
-
-
-
-
+    // end::refguide[]
     /**
      * The {@link org.apache.isis.applib.spec.Specification}(s) to be satisfied by this property.
      *
@@ -189,45 +193,42 @@ public @interface Property {
      * If more than one is provided, then all must be satisfied (in effect &quot;AND&quot;ed together).
      * </p>
      */
+    // tag::refguide[]
     Class<? extends Specification>[] mustSatisfy() default {};
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates whether the property should be included or excluded from mementos.
      *
      * <p>
-     *     To ensure that the property is actually not persisted in the objectstore, also annotate with the JDO annotation 
-     *     {@link javax.jdo.annotations.NotPersistent}.
+     *     To ensure that the property is actually not persisted in the objectstore, also annotate with the JDO annotation
+     *     <code>javax.jdo.annotations.NotPersistent</code>
      * </p>
      */
+    // tag::refguide[]
     MementoSerialization mementoSerialization() default MementoSerialization.NOT_SPECIFIED;
 
-
-
-
-
+    // end::refguide[]
     /**
      * Whether this property is optional or is mandatory (ie required).
      *
      * <p>
      *     For properties the default value, {@link org.apache.isis.applib.annotation.Optionality#DEFAULT}, usually
      *     means that the property is required unless it has been overridden by {@link javax.jdo.annotations.Column}
-     *     with its {@link javax.jdo.annotations.Column#allowsNull() allowsNull()} attribute set to true.
+     *     with its <code>javax.jdo.annotations.Column#allowsNull()</code> attribute set to true.
      * </p>
      */
+    // tag::refguide[]
     Optionality optionality() default Optionality.NOT_SPECIFIED;
 
-
-
-
-
+    // end::refguide[]
     /**
      * Regular expression pattern that a value should conform to, and can be formatted as.
      */
+    // tag::refguide[]
     String regexPattern() default "";
 
+    // end::refguide[]
     /**
      * Pattern flags, as per {@link java.util.regex.Pattern#compile(String, int)} .
      *
@@ -235,17 +236,17 @@ public @interface Property {
      *     The default value, <code>0</code>, means that no flags have been specified.
      * </p>
      */
+    // tag::refguide[]
     int regexPatternFlags() default 0;
 
+    // end::refguide[]
     /**
      * Replacement text for the pattern in generated error message.
      */
+    // tag::refguide[]
     String regexPatternReplacement() default "Doesn't match pattern";
 
-
-
-
-
+    // end::refguide[]
     /**
      * For uploading {@link Blob} or {@link Clob}, optionally restrict the files accepted (eg <tt>.xslx</tt>).
      *
@@ -255,7 +256,8 @@ public @interface Property {
      *
      * @see <a href="http://www.w3schools.com/tags/att_input_accept.asp">http://www.w3schools.com</a>
      */
+    // tag::refguide[]
     String fileAccept() default "";
 
-
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/PropertyLayout.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/PropertyLayout.java
index edd145d..11f965b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/PropertyLayout.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/PropertyLayout.java
@@ -30,28 +30,35 @@ import java.lang.annotation.Target;
  *
  * @see org.apache.isis.applib.annotation.ParameterLayout
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 @Mixin(method = "prop")
 public @interface PropertyLayout {
 
+    // end::refguide[]
     /**
      * Indicates the css class that a property should have.
      */
+    // tag::refguide[]
     String cssClass() default "";
 
+    // end::refguide[]
     /**
      * Description of this property, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
-
+    // end::refguide[]
     /**
      * Indicates where in the UI the property should <i>not</i>not be visible.
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * In forms, positioning of the label (left, top or none) relative to the property value.
      *
@@ -59,30 +66,41 @@ public @interface PropertyLayout {
      * If not specified, the default depends upon the property value's datatype.
      * </p>
      */
+    // tag::refguide[]
     LabelPosition labelPosition() default LabelPosition.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * For string properties (and parameters), render as a text area over specified number of lines.
      */
+    // tag::refguide[]
     int multiLine() default -1;
 
+    // end::refguide[]
     /**
      * Name of this property (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
+    // end::refguide[]
     /**
      * A flag indicating whether the value of {@linkplain #named()} should be HTML escaped or not.
      */
+    // tag::refguide[]
     boolean namedEscaped() default true;
 
+    // tag::refguide[]
     Navigable navigable() default Navigable.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * How the properties of this domain object are be edited, either {@link PromptStyle#DIALOG dialog} or {@link PromptStyle#INLINE inline}.
      */
+    // tag::refguide[]
     PromptStyle promptStyle() default PromptStyle.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * For date properties (and parameters) only, instructs the viewer that the date should be rendered as one day
      * prior to the actually stored date.
@@ -108,13 +126,17 @@ public @interface PropertyLayout {
      * In the domain object, itself, however, the value stored is 1-jun-2013.
      * </p>
      */
+    // tag::refguide[]
     RenderDay renderDay() default RenderDay.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * The typical entry length of a field, use to determine the optimum width for display
      */
+    // tag::refguide[]
     int typicalLength() default -1;
 
+    // end::refguide[]
     /**
      * Indicates that the value held by the property never changes over time, even when other properties of the object
      * do change.
@@ -137,7 +159,9 @@ public @interface PropertyLayout {
      *     within the framework than simply a hint for rendering.
      * </p>
      */
+    // tag::refguide[]
     Repainting repainting() default Repainting.NOT_SPECIFIED;
 
 }
+// end::refguide[]
 
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Publishing.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Publishing.java
index 581bdab..0afa406 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Publishing.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Publishing.java
@@ -21,7 +21,10 @@ package org.apache.isis.applib.annotation;
 /**
  * The available policies for publishing changes to the properties of the object.
  */
+// tag::refguide[]
 public enum Publishing {
+
+    // end::refguide[]
     /**
      * The publishing of the object should be as per the default publishing policy configured in <tt>application.properties</tt>.
      *
@@ -29,18 +32,30 @@ public enum Publishing {
      *     If no publishing policy is configured, then the publishing is disabled.
      * </p>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
+
+    // end::refguide[]
     /**
      * Publish changes to this object.
      */
+    // tag::refguide[]
     ENABLED,
+
+    // end::refguide[]
     /**
      * Do not publish changes to this object (even if otherwise configured to enable publishing).
      */
+    // tag::refguide[]
     DISABLED,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/PublishingChangeKind.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/PublishingChangeKind.java
index c7f7be7..48eba88 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/PublishingChangeKind.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/PublishingChangeKind.java
@@ -18,8 +18,14 @@
  */
 package org.apache.isis.applib.annotation;
 
+// tag::refguide[]
 public enum PublishingChangeKind {
+
     CREATE,
+
     UPDATE,
-    DELETE;
+
+    DELETE,
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Redirect.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Redirect.java
index fe999c8..20d1e38 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Redirect.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Redirect.java
@@ -24,20 +24,27 @@ import javax.xml.bind.annotation.XmlType;
  * The available policies for rendering the next page if the result is the same as the target
  * (in other words, an action that returns "this").
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum Redirect {
+
+    // end::refguide[]
     /**
      * As defined by configuration property <code>isis.viewer.wicket.redirectEvenIfSameObject</code>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
 
+    // end::refguide[]
     /**
      * Redirect (meaning render a new page) even if the result of the action is the same as the target.
      */
+    // tag::refguide[]
     EVEN_IF_SAME,
 
+    // end::refguide[]
     /**
      * Don't redirect if the result is the same as the target, instead just update the existing page.
      *
@@ -45,5 +52,8 @@ public enum Redirect {
      *     Of course, a redirect is still performed if the result of the action is different from the target.
      * </p>
      */
+    // tag::refguide[]
     ONLY_IF_DIFFERS,
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/RenderDay.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/RenderDay.java
index b5b60cd..15d79ed 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/RenderDay.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/RenderDay.java
@@ -23,18 +23,28 @@ import javax.xml.bind.annotation.XmlType;
 /**
  * How to render days.
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum RenderDay {
+
     AS_DAY,
+
+    // end::refguide[]
     /**
      * Equivalent to <tt>@PropertyLayout(renderAsDayBefore=true)</tt> prior to Isis 2.x
      */
+    // tag::refguide[]
     AS_DAY_BEFORE,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
-    NOT_SPECIFIED;
+    // tag::refguide[]
+    NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Repainting.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Repainting.java
index ffc0052..ed7c88e 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Repainting.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Repainting.java
@@ -23,18 +23,28 @@ import javax.xml.bind.annotation.XmlType;
 /**
  * Whether a component is unchanging and so does not require repainting.
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum Repainting {
+
     REPAINT,
+
+    // end::refguide[]
     /**
      * Equivalent to <tt>@PropertyLayout(unchanging=true)</tt> prior to Isis 2.x
      */
+    // tag::refguide[]
     NO_REPAINT,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/RestrictTo.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/RestrictTo.java
index 801939f..b7b395d 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/RestrictTo.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/RestrictTo.java
@@ -21,8 +21,14 @@ package org.apache.isis.applib.annotation;
 /**
  * Whether an action is restricted to development mode, or available in all.
  */
+// tag::refguide[]
 public enum RestrictTo {
+
     PROTOTYPING,
+
     NO_RESTRICTIONS,
+
     NOT_SPECIFIED;
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/SemanticsOf.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/SemanticsOf.java
index 553f2c7..49a0436 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/SemanticsOf.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/SemanticsOf.java
@@ -23,53 +23,63 @@ import org.apache.isis.applib.util.Enums;
 /**
  * @see <a href="https://isis.apache.org/guides/rgant/rgant.html#_rgant-Action_semantics">Reference Guide</a>
  */
+// tag::refguide[]
 public enum SemanticsOf {
 
+    // end::refguide[]
     /**
      * Safe, with no side effects, and caching the returned value when invoked multiple times in the same request.
      * <ul>
      * <li>Changes state: <b>No</b></li>
      * <li>HTTP verb: <b>GET</b></li>
-     * <li>Effect of multiple calls: Will <b>always return the same result</b> each time invoked 
+     * <li>Effect of multiple calls: Will <b>always return the same result</b> each time invoked
      * (within a given request scope).</li>
      * </ul>
      */
+    // tag::refguide[]
     SAFE_AND_REQUEST_CACHEABLE,
 
+    // end::refguide[]
     /**
      * Safe, with no side-effects. In other words, a query-only action.
      * <ul>
      * <li>Changes state: <b>No</b></li>
      * <li>HTTP verb: <b>GET</b></li>
-     * <li>Effect of multiple calls: Might result in <b>different results each invocation</b> 
+     * <li>Effect of multiple calls: Might result in <b>different results each invocation</b>
      * (within a given request scope).</li>
      * </ul>
      */
+    // tag::refguide[]
     SAFE,
 
+    // end::refguide[]
     /**
      * Post-conditions are always the same, irrespective as to how many times called.
      * <ul>
      * <li>Changes state: <b>Yes</b></li>
      * <li>HTTP verb: <b>PUT</b></li>
-     * <li>Effect of multiple calls: Will make <b>no further changes</b> if called multiple times 
+     * <li>Effect of multiple calls: Will make <b>no further changes</b> if called multiple times
      * (eg sets a property or adds of same item to a Set).</li>
      * </ul>
      */
+    // tag::refguide[]
     IDEMPOTENT,
 
+    // end::refguide[]
     /**
      * Neither safe nor idempotent; every invocation is likely to change the state of the object.
      * <ul>
      * <li>Changes state: <b>Yes</b></li>
      * <li>HTTP verb: <b>POST</b></li>
-     * <li>Effect of multiple calls: Might <b>change the state</b> of the system each time called 
+     * <li>Effect of multiple calls: Might <b>change the state</b> of the system each time called
      * (eg increments a counter or adds to a List).</li>
      * <li>Example: Increasing the quantity of a line item in an Order by 1.</li>
      * </ul>
      */
+    // tag::refguide[]
     NON_IDEMPOTENT,
 
+    // end::refguide[]
     /**
      * Post-conditions are always the same, irrespective as to how many times called.
      * <p>
@@ -77,12 +87,14 @@ public enum SemanticsOf {
      * <ul>
      * <li>Changes state: <b>Yes</b></li>
      * <li>HTTP verb: <b>PUT</b></li>
-     * <li>Effect of multiple calls: Will make <b>no further changes</b> if called multiple times 
+     * <li>Effect of multiple calls: Will make <b>no further changes</b> if called multiple times
      * (eg sets a property or adds of same item to a Set).</li>
      * </ul>
      */
+    // tag::refguide[]
     IDEMPOTENT_ARE_YOU_SURE,
 
+    // end::refguide[]
     /**
      * Neither safe nor idempotent; every invocation is likely to change the state of the object.
      * <p>
@@ -90,17 +102,23 @@ public enum SemanticsOf {
      * <ul>
      * <li>Changes state: <b>Yes</b></li>
      * <li>HTTP verb: <b>POST</b></li>
-     * <li>Effect of multiple calls: Might <b>change the state</b> of the system each time called 
+     * <li>Effect of multiple calls: Might <b>change the state</b> of the system each time called
      * (eg increments a counter or adds to a List).</li>
      * <li>Example: Increasing the quantity of a line item in an Order by 1.</li>
      */
+    // tag::refguide[]
     NON_IDEMPOTENT_ARE_YOU_SURE,
 
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
-    NOT_SPECIFIED;
+    // tag::refguide[]
+    NOT_SPECIFIED
+
+    // end::refguide[]
+    ;
 
     public String getFriendlyName() {
         return Enums.getFriendlyNameOf(this);
@@ -140,4 +158,7 @@ public enum SemanticsOf {
         return this == IDEMPOTENT_ARE_YOU_SURE || this == NON_IDEMPOTENT_ARE_YOU_SURE;
     }
 
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Title.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Title.java
index f7c3259..b6cd0c1 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Title.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Title.java
@@ -28,30 +28,44 @@ import java.lang.annotation.Target;
  * A title annotation used to annotate methods used to construct the title of a
  * domain object instance. It is used as a marker.
  */
+// tag::refguide[]
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ ElementType.METHOD, ElementType.FIELD })
+@Target({
+        ElementType.METHOD,
+        ElementType.FIELD
+})
 public @interface Title {
 
+    // end::refguide[]
     /**
      * The order (in Dewey decimal notation) that the property annotated with
      * {@link Title} appears with respect to other properties also annotated
      * with {@link Title}.
      */
+    // tag::refguide[]
     String sequence() default "1.0";
 
+    // end::refguide[]
     /**
      * The string to use to separate this property from any preceding properties
      * in the title.
      */
+    // tag::refguide[]
     String prepend() default " ";
 
+    // end::refguide[]
     /**
      * The string to append to this property if non-empty.
      */
+    // tag::refguide[]
     String append() default "";
 
+    // end::refguide[]
     /**
      * The length to abbreviate this title element to.
      */
+    // tag::refguide[]
     int abbreviatedTo() default Integer.MAX_VALUE;
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Value.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Value.java
index 03e8dd2..446bf84 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Value.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Value.java
@@ -54,11 +54,13 @@ import org.apache.isis.applib.adapters.ValueSemanticsProvider;
  *     Note: This annotation is only incompletely recognized by the framework, and may be deprecated in the future.
  * </p>
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Value {
 
+    // end::refguide[]
     /**
      * The fully qualified name of a class that implements the
      * {@link ValueSemanticsProvider} interface.
@@ -82,8 +84,10 @@ public @interface Value {
      * Implementation note: the default value provided here is simply an empty
      * string because <tt>null</tt> is not a valid default.
      */
+    // tag::refguide[]
     String semanticsProviderName() default "";
 
+    // end::refguide[]
     /**
      * As per {@link #semanticsProviderName()}, but specifying a class literal
      * rather than a fully qualified class name.
@@ -92,6 +96,8 @@ public @interface Value {
      * Implementation note: the default value provided here is simply the
      * {@link Value}'s own class, because <tt>null</tt> is not a valid default.
      */
+    // tag::refguide[]
     Class<?> semanticsProviderClass() default Value.class;
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/ViewModel.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/ViewModel.java
index e76c9d2..8c4b8c7 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/ViewModel.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/ViewModel.java
@@ -51,14 +51,18 @@ import org.springframework.stereotype.Component;
  * @see ViewModel
  * 
  * @apiNote Meta annotation {@link Component} allows for the Spring framework to pick up (discover) the 
- * annotated type. 
- * For more details see {@link org.apache.isis.config.beans.IsisBeanFactoryPostProcessorForSpring}.
+ * annotated type.
+ *
+ * For more details see <code>org.apache.isis.config.beans.IsisBeanFactoryPostProcessorForSpring</code>.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Component @Scope("prototype")
 public @interface ViewModel {
-
-
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/ViewModelLayout.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/ViewModelLayout.java
index f2972f8..c748e84 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/ViewModelLayout.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/ViewModelLayout.java
@@ -46,11 +46,16 @@ import org.apache.isis.applib.layout.component.CssClassFaPosition;
  *      with just <tt>@ViewModel</tt> and <tt>@ViewModelLayout</tt>.
  * </p>
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ViewModelLayout {
 
+    // end::refguide[]
     /**
      * Which subclass of {@link TitleUiEvent} should be used to obtain a title.
      *
@@ -58,10 +63,10 @@ public @interface ViewModelLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends TitleUiEvent<?>> titleUiEvent() default TitleUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link IconUiEvent} should be used to obtain an icon.
      *
@@ -69,10 +74,10 @@ public @interface ViewModelLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends IconUiEvent<?>> iconUiEvent() default IconUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link CssClassUiEvent} should be used to obtain a CSS class.
      *
@@ -80,10 +85,10 @@ public @interface ViewModelLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CssClassUiEvent<?>> cssClassUiEvent() default CssClassUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link LayoutUiEvent} should be used to obtain a layout.
      *
@@ -91,22 +96,25 @@ public @interface ViewModelLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends LayoutUiEvent<?>> layoutUiEvent() default LayoutUiEvent.Default.class;
 
-
+    // end::refguide[]
     /**
      * Indicates the css class that a domain class (type) should have.
      */
+    // tag::refguide[]
     String cssClass() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a> CSS class to decorate an
      * domain object.
      */
+    // tag::refguide[]
     String cssClassFa() default "";
 
+    // end::refguide[]
     /**
      * Indicates the position of the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a>
      * icon. The icon could be rendered on the left or the right of the object's title.
@@ -115,26 +123,24 @@ public @interface ViewModelLayout {
      *     This attribute is currently ignored by Isis viewers.
      * </p>
      */
+    // tag::refguide[]
     CssClassFaPosition cssClassFaPosition() default CssClassFaPosition.LEFT;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Description of this class, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Name of this class (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The page size for instances of this class when rendered within
      * a table.
@@ -147,21 +153,22 @@ public @interface ViewModelLayout {
      * If annotated on a type, then the page size refers to standalone
      * collections (eg as returned from a repository query).
      */
+    // tag::refguide[]
     int paged() default -1;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The plural name of the class.
      */
+    // tag::refguide[]
     String plural() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Whether (and how) this domain object can be bookmarked in the UI.
      */
+    // tag::refguide[]
     BookmarkPolicy bookmarking() default BookmarkPolicy.NOT_SPECIFIED;
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/annotation/Where.java b/api/applib/src/main/java/org/apache/isis/applib/annotation/Where.java
index 497b111..c1d01c2 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/annotation/Where.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/annotation/Where.java
@@ -40,41 +40,63 @@ import org.apache.isis.applib.util.Enums;
  * This enum is also used internally within the framework.  When rendering an element,
  * the framework developer should only use those values that represent concrete locations.
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum Where {
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden everywhere.
      *
      * <p>
      * Synonym for {@link #ANYWHERE}.
      */
+    // tag::refguide[]
     EVERYWHERE {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return true;
         }
+
+        // tag::refguide[]
+        // ...
     },
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden everywhere.
      *
      * <p>
      * Synonym for {@link #EVERYWHERE}.
      */
+    // tag::refguide[]
     ANYWHERE {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return true;
         }
+
+        // tag::refguide[]
+        // ...
     },
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden when displayed within an object form.
      *
      * <p>
      * For most viewers, this applies to property and collection members, not actions.
      */
+    // tag::refguide[]
     OBJECT_FORMS,
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden when displayed as a column of a table
      * within parent object's collection, and references that parent.
@@ -82,7 +104,10 @@ public enum Where {
      * <p>
      * For most (all?) viewers, this will have meaning only if applied to a property member.
      */
+    // tag::refguide[]
     REFERENCES_PARENT,
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden when displayed as a column of a table within
      * a parent object's collection.
@@ -90,7 +115,10 @@ public enum Where {
      * <p>
      * For most (all?) viewers, this will have meaning only if applied to a property member.
      */
+    // tag::refguide[]
     PARENTED_TABLES ,
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden when displayed as a column of a table showing a standalone list
      * of objects, for example as returned by a repository query.
@@ -98,7 +126,10 @@ public enum Where {
      * <p>
      * For most (all?) viewers, this will have meaning only if applied to a property member.
      */
+    // tag::refguide[]
     STANDALONE_TABLES,
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden when displayed as a column of a table, either an object's
      * collection or a standalone list.
@@ -106,24 +137,40 @@ public enum Where {
      * <p>
      * This combines {@link #PARENTED_TABLES} and {@link #STANDALONE_TABLES}.
      */
+    // tag::refguide[]
     ALL_TABLES {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return context == this || context == PARENTED_TABLES || context == STANDALONE_TABLES;
         }
+
+        // tag::refguide[]
+        // ...
     },
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden except when displayed as a column of a standalone table.
      *
      * <p>
      * This is the inverse of {@link #STANDALONE_TABLES}.
      */
+    // tag::refguide[]
     ALL_EXCEPT_STANDALONE_TABLES {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return context != STANDALONE_TABLES;
         }
+
+        // tag::refguide[]
+        // ...
     },
+
+    // end::refguide[]
     /**
      * To act as an override if a member would normally be hidden as a result of some other convention.
      *
@@ -131,22 +178,37 @@ public enum Where {
      * For example, if a property is annotated with <tt>@Title</tt>, then normally this should be hidden
      * from all tables.  Additionally annotating with <tt>@Hidden(where=Where.NOWHERE)</tt> overrides this.
      */
+    // tag::refguide[]
     NOWHERE {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return false;
         }
+
+        // tag::refguide[]
+        // ...
     },
+
+    // end::refguide[]
     /**
      * Acts as the default no-op value for {@link PropertyLayout#hidden()}, {@link CollectionLayout#hidden()} and {@link ActionLayout#hidden()}.
      */
+    // tag::refguide[]
     NOT_SPECIFIED {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return false;
         }
+
+        // tag::refguide[]
+        // ...
     };
 
+    // end::refguide[]
     public String getFriendlyName() {
         return Enums.getFriendlyNameOf(this);
     }
@@ -169,4 +231,7 @@ public enum Where {
         return context == this;
     }
 
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/client/SuppressionType.java b/api/applib/src/main/java/org/apache/isis/applib/client/SuppressionType.java
index dd0ff85..4a0a42c 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/client/SuppressionType.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/client/SuppressionType.java
@@ -29,25 +29,52 @@ import static org.apache.isis.core.commons.internal.base._NullSafe.stream;
  * 
  * @since 2.0
  */
+// tag::refguide[]
 public enum SuppressionType {
 
-    /** suppress '$$RO', RO Spec representation*/
+    // end::refguide[]
+    /**
+     * suppress '$$RO', RO Spec representation
+     */
+    // tag::refguide[]
     RO,
 
-    /** suppress '$$href', hyperlink to the representation*/
+    // end::refguide[]
+    /**
+     * suppress '$$href', hyperlink to the representation
+     */
+    // tag::refguide[]
     HREF,
 
-    /** suppress '$$instanceId', instance id of the domain object*/
+    // end::refguide[]
+    /**
+     suppress '$$instanceId', instance id of the domain object
+     */
+    // tag::refguide[]
     ID,
 
-    /** suppress '$$domainType', object spec of the domain object */
+    // end::refguide[]
+    /**
+     * suppress '$$domainType', object spec of the domain object
+     */
+    // tag::refguide[]
     DOMAIN_TYPE,
 
-    /** suppress '$$title', title of the domain object*/
+    // end::refguide[]
+    /**
+     * suppress '$$title', title of the domain object
+     */
+    // tag::refguide[]
     TITLE,
 
-    /** suppress all '$$...' entries*/
+    // end::refguide[]
+    /**
+     * suppress all '$$...' entries
+     */
+    // tag::refguide[]
     ALL
+
+    // end::refguide[]
     ;
 
     public static EnumSet<SuppressionType> setOf(SuppressionType ... types){
@@ -74,7 +101,7 @@ public enum SuppressionType {
 
             // honor pre v2 behavior
             if("true".equalsIgnoreCase(literal)) {
-                return SuppressionType.RO; 
+                return SuppressionType.RO;
             }
 
             try {
@@ -83,9 +110,8 @@ public enum SuppressionType {
                 return null;
             }
         }
-
     }
+    // tag::refguide[]
 
-
-
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/EventObjectBase.java b/api/applib/src/main/java/org/apache/isis/applib/events/EventObjectBase.java
similarity index 89%
rename from api/applib/src/main/java/org/apache/isis/applib/events/domain/EventObjectBase.java
rename to api/applib/src/main/java/org/apache/isis/applib/events/EventObjectBase.java
index 06a9edb..2cee75b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/EventObjectBase.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/EventObjectBase.java
@@ -16,7 +16,7 @@
  *  specific language governing permissions and limitations
  *  under the License.
  */
-package org.apache.isis.applib.events.domain;
+package org.apache.isis.applib.events;
 
 import javax.annotation.Nullable;
 
@@ -27,36 +27,44 @@ import static org.apache.isis.core.commons.internal.base._With.requires;
 /**
  * @since 2.0
  */
+// tag::refguide[]
 public abstract class EventObjectBase<T> {
 
+    // end::refguide[]
     /**
      * The object on which the Event initially occurred.
      */
+    // tag::refguide[]
     protected transient T source;
 
+    // end::refguide[]
     /**
      * Constructs a prototypical Event.
      *
      * @param    source    The object on which the Event initially occurred.
      */
+    // tag::refguide[]
     protected EventObjectBase(@Nullable T source) {
         this.source = source;
     }
 
+    // end::refguide[]
     /**
      * The object on which the Event initially occurred.
      *
      * @return   The object on which the Event initially occurred.
      */
+    // tag::refguide[]
     public @Nullable T getSource() {
         return source;
     }
-    
+
+    // end::refguide[]
     /**
      * A one-shot function. Only allowed to be called if a source has not already been set.
-     * 
+     *
      * @apiNote reserved for framework internal use
-     * 
+     *
      * @param source non-null
      */
     public void initSource(T source) {
@@ -75,5 +83,7 @@ public abstract class EventObjectBase<T> {
     public String toString() {
         return getClass().getName() + "[source=" + source + "]";
     }
-    
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/AbstractDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/AbstractDomainEvent.java
index 16aef719..4ca383c 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/AbstractDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/AbstractDomainEvent.java
@@ -23,19 +23,24 @@ import java.util.Map;
 
 import org.apache.isis.applib.Identifier;
 import org.apache.isis.applib.annotation.Programmatic;
+import org.apache.isis.applib.events.EventObjectBase;
 import org.apache.isis.applib.services.command.CommandContext;
 import org.apache.isis.applib.services.i18n.TranslatableString;
 import org.apache.isis.applib.util.ObjectContracts;
 import org.apache.isis.applib.util.ToString;
 import org.apache.isis.core.commons.internal.exceptions._Exceptions;
 
+import lombok.Getter;
+
+// tag::refguide[]
 public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
 
+    // end::refguide[]
     /**
      * If used then the framework will set state via (non-API) setters.
      *
      * <p>
-     *     Because the {@link EventObjectBase} superclass prohibits a null source, 
+     *     Because the {@link EventObjectBase} superclass prohibits a null source,
      *     a dummy value is temporarily used.
      * </p>
      */
@@ -50,16 +55,14 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         this.identifier = identifier;
     }
 
-    // - mixedIn
-
-    private Object mixedIn;
-
     /**
      * Populated only for mixins; holds the underlying domain object that the mixin contributes to.
      */
-    public Object getMixedIn() {
-        return mixedIn;
-    }
+    // tag::refguide[]
+    @Getter
+    private Object mixedIn;
+
+    // end::refguide[]
     /**
      * Not API - set by the framework.
      */
@@ -68,28 +71,32 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
     }
 
 
-
-    // -- Subject
-
     /**
      * The subject of the event, which will be either the {@link #getSource() source} for a regular action, or the
      * {@link #getMixedIn() mixed-in} domain object for a mixin.
      */
+    // tag::refguide[]
     public Object getSubject() {
         final Object mixedIn = getMixedIn();
         return mixedIn != null ? mixedIn : getSource();
     }
 
-
-
-    // -- Phase
-
+    // end::refguide[]
+    // tag::refguide-1[]
     public enum Phase {
+
         HIDE,
+
         DISABLE,
+
         VALIDATE,
+
         EXECUTING,
-        EXECUTED;
+
+        EXECUTED
+
+        // end::refguide-1[]
+        ;
 
         /**
          * The significance being that at this point the proposed values/arguments are known, and so the event can be
@@ -114,34 +121,35 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         public boolean isExecuted() {
             return this == EXECUTED;
         }
-    }
+        // tag::refguide-1[]
 
-    private Phase phase;
+    }
+    // end::refguide-1[]
 
     /**
      * Whether the framework is checking visibility, enablement, validity or actually executing (invoking action,
      * updating property or collection).
      */
-    public Phase getEventPhase() {
-        return phase;
-    }
+    // tag::refguide[]
+    @Getter
+    private Phase eventPhase;
 
+    // end::refguide[]
     /**
      * Not API, set by the framework.
      */
     public void setEventPhase(Phase phase) {
-        this.phase = phase;
+        this.eventPhase = phase;
     }
 
-    // -- identifier
     /**
      * If the no-arg constructor is used, then the framework will populate this field reflectively.
      */
+    // tag::refguide[]
+    @Getter
     private Identifier identifier;
-    public Identifier getIdentifier() {
-        return identifier;
-    }
 
+    // end::refguide[]
     /**
      * Not API, set by the framework if the no-arg constructor is used.
      */
@@ -149,98 +157,117 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         this.identifier = identifier;
     }
 
-
-    // -- hide, isHidden
+    @Getter
     private boolean hidden;
-    public boolean isHidden() {
-        return hidden;
-    }
 
     /**
      * @see #veto(String, Object...)
      */
+    // tag::refguide[]
     public void hide() {
+        // end::refguide[]
+
         this.hidden = true;
-    }
 
+        // tag::refguide[]
+        // ...
+    }
+    // end::refguide[]
 
-    // -- disable, isDisabled, getDisabledReason, getDisabledReasonTranslatable
+    /**
+     * If {@link #isDisabled() disabled}, then either this method returns non-null or {@link #getDisabledReasonTranslatable()} will.
+     */
+    @Getter
     private String disabledReason;
 
+    /**
+     * If {@link #isDisabled() disabled}, then either this method returns non-null or {@link #getDisabledReason()} will.
+     */
+    @Getter
+    private TranslatableString disabledReasonTranslatable;
+
     public boolean isDisabled() {
         return disabledReason != null || disabledReasonTranslatable != null;
     }
 
-    /**
-     * If {@link #isDisabled() disabled}, then either this method returns non-null or {@link #getDisabledReasonTranslatable()} will.
-     */
-    public String getDisabledReason() {
-        return disabledReason;
-    }
 
     /**
      * @see #disable(org.apache.isis.applib.services.i18n.TranslatableString)
      * @see #veto(String, Object...)
      */
+    // tag::refguide[]
     public void disable(final String reason) {
+        // end::refguide[]
+
         this.disabledReason = reason;
-    }
 
-    private TranslatableString disabledReasonTranslatable;
-    /**
-     * If {@link #isDisabled() disabled}, then either this method returns non-null or {@link #getDisabledReason()} will.
-     */
-    public TranslatableString getDisabledReasonTranslatable() {
-        return disabledReasonTranslatable;
+        // tag::refguide[]
+        // ...
     }
+    // end::refguide[]
+
     /**
      * @see #disable(java.lang.String)
      * @see #veto(org.apache.isis.applib.services.i18n.TranslatableString)
      */
+    // tag::refguide[]
     public void disable(final TranslatableString reason) {
-        this.disabledReasonTranslatable = reason;
-    }
+        // end::refguide[]
 
+        this.disabledReasonTranslatable = reason;
 
-    // -- invalidate, isInvalid, getInvalidityReason, getInvalidityReasonTranslatable
-    private String invalidatedReason;
-    public boolean isInvalid() {
-        return invalidatedReason != null || invalidatedReasonTranslatable != null;
+        // tag::refguide[]
+        // ...
     }
+    // end::refguide[]
+
 
     /**
      * If {@link #isInvalid() invalid}, then either this method returns non-null or {@link #getInvalidityReasonTranslatable()} will.
      */
-    public String getInvalidityReason() {
-        return invalidatedReason;
+    @Getter
+    private String invalidityReason;
+
+    /**
+     * If {@link #isInvalid() invalid}, then either this method returns non-null or {@link #getInvalidityReason()} will.
+     */
+    @Getter
+    private TranslatableString invalidityReasonTranslatable;
+
+    public boolean isInvalid() {
+        return invalidityReason != null || invalidityReasonTranslatable != null;
     }
+
     /**
      * @see #invalidate(org.apache.isis.applib.services.i18n.TranslatableString)
      * @see #veto(String, Object...)
      */
+    // tag::refguide[]
     public void invalidate(final String reason) {
-        this.invalidatedReason = reason;
-    }
+        // end::refguide[]
 
-    private TranslatableString invalidatedReasonTranslatable;
-    /**
-     * If {@link #isInvalid() invalid}, then either this method returns non-null or {@link #getInvalidityReason()} will.
-     */
-    public TranslatableString getInvalidityReasonTranslatable() {
-        return invalidatedReasonTranslatable;
+        this.invalidityReason = reason;
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * @see #invalidate(String)
      * @see #veto(org.apache.isis.applib.services.i18n.TranslatableString)
      */
+    // tag::refguide[]
     public void invalidate(final TranslatableString reason) {
-        this.invalidatedReasonTranslatable = reason;
-    }
+        // end::refguide[]
 
+        this.invalidityReasonTranslatable = reason;
 
+        // tag::refguide[]
+        // ...
+    }
+    // end::refguide[]
 
-    // -- veto
     /**
      * Use instead of {@link #hide()}, {@link #disable(String)} and {@link #invalidate(String)}; just delegates to
      * appropriate vetoing method based upon the {@link #getEventPhase() phase}.
@@ -254,8 +281,10 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
      *
      * @see #veto(org.apache.isis.applib.services.i18n.TranslatableString)
      */
-    @Programmatic
+    // tag::refguide[]
     public void veto(final String reason, final Object... args) {
+        // end::refguide[]
+
         switch (getEventPhase()) {
         case HIDE:
             hide();
@@ -278,7 +307,12 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         default:
             throw _Exceptions.unmatchedCase(getEventPhase());
         }
+
+        // tag::refguide[]
+        // ...
     }
+
+    // end::refguide[]
     /**
      * Use instead of {@link #hide()}, {@link #disable(org.apache.isis.applib.services.i18n.TranslatableString)} and {@link #invalidate(org.apache.isis.applib.services.i18n.TranslatableString)}; just delegates to
      * appropriate vetoing method based upon the {@link #getEventPhase() phase}.
@@ -291,8 +325,10 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
      *
      * @see #veto(String, Object...)
      */
-    @Programmatic
+    // tag::refguide[]
     public void veto(final TranslatableString translatableReason) {
+        // end::refguide[]
+
         switch (getEventPhase()) {
         case HIDE:
             hide();
@@ -309,10 +345,12 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         default:
             throw _Exceptions.unmatchedCase(getEventPhase());
         }
-    }
 
+        // tag::refguide[]
+        // ...
+    }
+    // end::refguide[]
 
-    // -- userData
     /**
      * Provides a mechanism to pass data to the next {@link #getEventPhase() phase}.
      */
@@ -321,15 +359,20 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
     /**
      * Obtain user-data, as set by a previous {@link #getEventPhase() phase}.
      */
+    // tag::refguide[]
     public Object get(Object key) {
         return userData.get(key);
     }
+
+    // end::refguide[]
     /**
      * Set user-data, for the use of a subsequent {@link #getEventPhase() phase}.
      */
+    // tag::refguide[]
     public void put(Object key, Object value) {
         userData.put(key, value);
     }
+    // end::refguide[]
 
     private static final ToString<AbstractDomainEvent<?>> toString =
             ObjectContracts.<AbstractDomainEvent<?>>
@@ -343,5 +386,7 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         return toString.toString(this);
     }
 
+    // tag::refguide[]
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java
index 9c66001..b935e91 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/ActionDomainEvent.java
@@ -24,37 +24,38 @@ import org.apache.isis.applib.annotation.SemanticsOf;
 import org.apache.isis.applib.util.ObjectContracts;
 import org.apache.isis.applib.util.ToString;
 
+import lombok.Getter;
+
+// tag::refguide[]
 public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
 
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.Action#domainEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.action.domain-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ActionDomainEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ActionDomainEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ActionDomainEvent<Object> {}
 
-
-
+    // end::refguide[]
     /**
      * If used then the framework will set state via (non-API) setters.
      *
@@ -87,95 +88,34 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
     //    }
 
 
-    // -- actionSemantics
-    public SemanticsOf getSemantics() {
-        return actionSemantics;
-    }
-
-    private SemanticsOf actionSemantics;
+    // tag::refguide[]
+    @Getter
+    private SemanticsOf semantics;
 
-    /**
-     * @deprecated - use {@link #getSemantics()} instead.
-     */
-    @Deprecated
-    public SemanticsOf getActionSemantics() {
-        return actionSemantics;
-    }
-
-    /**
-     * Not API - set by the framework.
-     */
-    public void setActionSemantics(SemanticsOf actionSemantics) {
-        this.actionSemantics = actionSemantics;
-    }
-
-
-
-    // -- parameterNames
+    @Getter
     private List<String> parameterNames;
-    public List<String> getParameterNames() {
-        return parameterNames;
-    }
-    public void setParameterNames(final List<String> parameterNames) {
-        this.parameterNames = parameterNames;
-    }
-
 
-    // -- parameterTypes
+    @Getter
     private List<Class<?>> parameterTypes;
-    public List<Class<?>> getParameterTypes() {
-        return parameterTypes;
-    }
-
-    public void setParameterTypes(final List<Class<?>> parameterTypes) {
-        this.parameterTypes = parameterTypes;
-    }
-
-
-
-    // region > mixedIn
-    private Object mixedIn;
 
+    // end::refguide[]
     /**
      * Populated only for mixins; holds the underlying domain object that the mixin contributes to.
      */
-    @Override
-    public Object getMixedIn() {
-        return mixedIn;
-    }
-    /**
-     * Not API - set by the framework.
-     */
-    @Override
-    public void setMixedIn(final Object mixedIn) {
-        this.mixedIn = mixedIn;
-    }
-    // endregion
+    // tag::refguide[]
+    @Getter
+    private Object mixedIn;
 
-    // -- arguments
-    private List<Object> arguments;
+    // end::refguide[]
     /**
      * The arguments being used to invoke the action; populated at {@link Phase#VALIDATE} and subsequent phases
      * (but null for {@link Phase#HIDE hidden} and {@link Phase#DISABLE disable} phases).
      */
-    public List<Object> getArguments() {
-        return arguments;
-    }
-
-    /**
-     * Not API - set by the framework.
-     */
-    public void setArguments(List<Object> arguments) {
-        this.arguments = arguments;
-    }
-
-
-    // -- returnValue
-    /**
-     *
-     */
-    private Object returnValue;
+    // tag::refguide[]
+    @Getter
+    private List<Object> arguments;
 
+    // end::refguide[]
     /**
      * The value returned by the action.
      *
@@ -184,20 +124,54 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
      *     {@link #getEventPhase() phase}.
      * </p>
      */
-    public Object getReturnValue() {
-        return returnValue;
-    }
+    // tag::refguide[]
+    @Getter
+    private Object returnValue;
 
+    // end::refguide[]
     /**
      * Set by the framework.
      *
      * Event subscribers can replace the value with some other value if they wish, though only in the
      * {@link Phase#EXECUTED} phase.
      */
+    // tag::refguide[]
     public void setReturnValue(final Object returnValue) {
         this.returnValue = returnValue;
     }
 
+    // end::refguide[]
+    /**
+     * Not API - set by the framework.
+     */
+    public void setSemantics(SemanticsOf semantics) {
+        this.semantics = semantics;
+    }
+    /**
+     * Not API - set by the framework.
+     */
+    public void setParameterNames(final List<String> parameterNames) {
+        this.parameterNames = parameterNames;
+    }
+    /**
+     * Not API - set by the framework.
+     */
+    public void setParameterTypes(final List<Class<?>> parameterTypes) {
+        this.parameterTypes = parameterTypes;
+    }
+    /**
+     * Not API - set by the framework.
+     */
+    @Override
+    public void setMixedIn(final Object mixedIn) {
+        this.mixedIn = mixedIn;
+    }
+    /**
+     * Not API - set by the framework.
+     */
+    public void setArguments(List<Object> arguments) {
+        this.arguments = arguments;
+    }
 
 
     private static final ToString<ActionDomainEvent<?>> toString = ObjectContracts.<ActionDomainEvent<?>>
@@ -211,5 +185,7 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
         return toString.toString(this);
     }
 
+    // tag::refguide[]
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java
index fe5826a..3bf5192 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/CollectionDomainEvent.java
@@ -21,38 +21,38 @@ package org.apache.isis.applib.events.domain;
 import org.apache.isis.applib.util.ObjectContracts;
 import org.apache.isis.applib.util.ToString;
 
+import lombok.Getter;
+
+// tag::refguide[]
 public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S> {
 
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.Collection#domainEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.collection.domain-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends CollectionDomainEvent<Object, Object> { }
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends CollectionDomainEvent<Object, Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends CollectionDomainEvent<Object, Object> {}
 
-
-
-    // -- constructor
+    // end::refguide[]
 
     /**
      * If used then the framework will set state via (non-API) setters.
@@ -66,52 +66,54 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S>
 
 
 
-    // -- value
-    private T value;
-
     /**
      * The proposed reference to either add or remove (per {@link #getOf()}), populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE}
      * and subsequent phases (is null for {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden} and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
      */
-    public T getValue() {
-        return value;
-    }
-    /**
-     * Not API, set by the framework.
-     */
-    public void setValue(T value) {
-        this.value = value;
-    }
-
+    // tag::refguide[]
+    @Getter
+    private T value;
 
-    // -- Of
     public static enum Of {
+        // end::refguide[]
         /**
          * The collection is being accessed
          * ({@link Phase#HIDE hide} and
          * {@link Phase#DISABLE disable}) checks.
          */
+        // tag::refguide[]
         ACCESS,
+
+        // end::refguide[]
         /**
          * The collection is being added to
          * ({@link Phase#VALIDATE validity} check and
          * {@link Phase#EXECUTED execution}).
          */
+        // tag::refguide[]
         ADD_TO,
+
+        // end::refguide[]
         /**
          * The collection is being removed from
          * ({@link Phase#VALIDATE validity} check and
          * {@link Phase#EXECUTED execution}).
          */
+        // tag::refguide[]
         REMOVE_FROM
+
     }
 
+    @Getter
     private Of of;
 
-    public Of getOf() {
-        return of;
+    // end::refguide[]
+    /**
+     * Not API, set by the framework.
+     */
+    public void setValue(T value) {
+        this.value = value;
     }
-
     /**
      * Not API; updates from {@link Of#ACCESS} to either {@link Of#ADD_TO} or {@link Of#REMOVE_FROM} when hits the
      * {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE validation phase}.
@@ -121,7 +123,6 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S>
     }
 
 
-
     private static final ToString<CollectionDomainEvent<?,?>> toString =
             ObjectContracts.<CollectionDomainEvent<?,?>>
     toString("source", CollectionDomainEvent::getSource)
@@ -136,4 +137,7 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S>
         return toString.toString(this);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java
index a8649b4..405f4a5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/domain/PropertyDomainEvent.java
@@ -21,38 +21,38 @@ package org.apache.isis.applib.events.domain;
 import org.apache.isis.applib.util.ObjectContracts;
 import org.apache.isis.applib.util.ToString;
 
+import lombok.Getter;
+
+// tag::refguide[]
 public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
 
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.Property#domainEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.property.domain-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends PropertyDomainEvent<Object, Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends PropertyDomainEvent<Object, Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends PropertyDomainEvent<Object, Object> {}
 
-
-    // -- constructors
-
+    // end::refguide[]
     /**
      * If used then the framework will set state via (non-API) setters.
      *
@@ -63,17 +63,25 @@ public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
     public PropertyDomainEvent() {
     }
 
-
-    // -- oldValue
+    // end::refguide[]
+    /**
+     * The current (pre-modification) value of the property; populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
+     * (but null for {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden} and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
+     */
+    // tag::refguide[]
+    @Getter
     private T oldValue;
 
+    // end::refguide[]
     /**
-     * The current (pre-modification) value of the property; populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
+     * The proposed (post-modification) value of the property; populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
      * (but null for {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden} and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
      */
-    public T getOldValue() {
-        return oldValue;
-    }
+    // tag::refguide[]
+    @Getter
+    private T newValue;
+
+    // end::refguide[]
     /**
      * Not API; for framework use only.
      */
@@ -81,16 +89,6 @@ public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
         this.oldValue = oldValue;
     }
 
-
-    // -- newValue
-    private T newValue;
-    /**
-     * The proposed (post-modification) value of the property; populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
-     * (but null for {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden} and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
-     */
-    public T getNewValue() {
-        return newValue;
-    }
     /**
      * Not API; for framework use only.
      */
@@ -113,4 +111,7 @@ public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
         return toString.toString(this);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/AbstractLifecycleEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/AbstractLifecycleEvent.java
index 2915043..33be455 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/AbstractLifecycleEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/AbstractLifecycleEvent.java
@@ -18,8 +18,9 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
-import org.apache.isis.applib.events.domain.EventObjectBase;
+import org.apache.isis.applib.events.EventObjectBase;
 
+// tag::refguide[]
 public abstract class AbstractLifecycleEvent<S> extends EventObjectBase<S> {
 
     public AbstractLifecycleEvent() {
@@ -30,4 +31,5 @@ public abstract class AbstractLifecycleEvent<S> extends EventObjectBase<S> {
         super(source);
     }
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectCreatedEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectCreatedEvent.java
index 061d5c1..1a2482e 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectCreatedEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectCreatedEvent.java
@@ -18,41 +18,44 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectCreatedEvent<S> extends AbstractLifecycleEvent<S> {
 
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#createdLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.created-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ObjectCreatedEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ObjectCreatedEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ObjectCreatedEvent<Object> {}
 
-
+    // end::refguide[]
     public ObjectCreatedEvent() {
     }
-    
+
     public ObjectCreatedEvent(final S source) {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectLoadedEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectLoadedEvent.java
index e1713c7..acc5780 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectLoadedEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectLoadedEvent.java
@@ -18,43 +18,44 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectLoadedEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#loadedLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.loaded-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ObjectLoadedEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ObjectLoadedEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ObjectLoadedEvent<Object> {}
 
-
+    // end::refguide[]
     public ObjectLoadedEvent() {
     }
-    
+
     public ObjectLoadedEvent(final S source) {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistedEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistedEvent.java
index 019f82b..cf364b6 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistedEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistedEvent.java
@@ -18,43 +18,45 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectPersistedEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#persistedLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.persisted-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+     // tag::refguide[]
     public static class Default extends ObjectPersistedEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+     // tag::refguide[]
     public static class Noop extends ObjectPersistedEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+     // tag::refguide[]
     public static class Doop extends ObjectPersistedEvent<Object> {}
 
+    // end::refguide[]
 
     public ObjectPersistedEvent() {
     }
-    
+
     public ObjectPersistedEvent(final S source) {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistingEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistingEvent.java
index 27527f7..6f5c070 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistingEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectPersistingEvent.java
@@ -18,37 +18,36 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectPersistingEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#persistingLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.persisting-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+     // tag::refguide[]
     public static class Default extends ObjectPersistingEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+     // tag::refguide[]
     public static class Noop extends ObjectPersistingEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+     // tag::refguide[]
     public static class Doop extends ObjectPersistingEvent<Object> {}
 
+    // end::refguide[]
 
     public ObjectPersistingEvent() {
     }
@@ -56,4 +55,7 @@ public abstract class ObjectPersistingEvent<S> extends AbstractLifecycleEvent<S>
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectRemovingEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectRemovingEvent.java
index eb606cf..6ad99af 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectRemovingEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectRemovingEvent.java
@@ -18,37 +18,36 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectRemovingEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#removingLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.removing-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ObjectRemovingEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ObjectRemovingEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ObjectRemovingEvent<Object> {}
 
+    // end::refguide[]
 
     public ObjectRemovingEvent() {
     }
@@ -57,4 +56,7 @@ public abstract class ObjectRemovingEvent<S> extends AbstractLifecycleEvent<S> {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatedEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatedEvent.java
index 4cf4a48..4e2f080 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatedEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatedEvent.java
@@ -18,37 +18,36 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectUpdatedEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#updatedLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.updated-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ObjectUpdatedEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ObjectUpdatedEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ObjectUpdatedEvent<Object> {}
 
+    // end::refguide[]
 
     public ObjectUpdatedEvent() {
     }
@@ -57,4 +56,7 @@ public abstract class ObjectUpdatedEvent<S> extends AbstractLifecycleEvent<S> {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatingEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatingEvent.java
index 8258ff9..c0a4813 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatingEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/lifecycle/ObjectUpdatingEvent.java
@@ -18,37 +18,36 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectUpdatingEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#updatingLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.updating-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ObjectUpdatingEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ObjectUpdatingEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ObjectUpdatingEvent<Object> {}
 
+    // end::refguide[]
 
     public ObjectUpdatingEvent() {
     }
@@ -57,4 +56,7 @@ public abstract class ObjectUpdatingEvent<S> extends AbstractLifecycleEvent<S> {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/ui/AbstractUiEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/ui/AbstractUiEvent.java
index 72df250..b57be4a 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/ui/AbstractUiEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/ui/AbstractUiEvent.java
@@ -21,11 +21,12 @@ package org.apache.isis.applib.events.ui;
 import java.util.HashMap;
 import java.util.Map;
 
-import org.apache.isis.applib.events.domain.EventObjectBase;
+import org.apache.isis.applib.events.EventObjectBase;
 
+// tag::refguide[]
 public abstract class AbstractUiEvent<S> extends EventObjectBase<S> {
 
-    // -- constructors
+    // end::refguide[]
     /**
      * If used then the framework will set state via (non-API) setters.
      *
@@ -38,7 +39,6 @@ public abstract class AbstractUiEvent<S> extends EventObjectBase<S> {
         super(source);
     }
 
-    // -- userData
     /**
      * Provides a mechanism to pass data around.
      */
@@ -47,14 +47,17 @@ public abstract class AbstractUiEvent<S> extends EventObjectBase<S> {
     /**
      * Obtain user-data, as set by any other subscribers.
      */
+    // tag::refguide[]
     public Object get(Object key) {
         return userData.get(key);
     }
     /**
      * Set user-data, for the use of other subscribers.
      */
+    // tag::refguide[]
     public void put(Object key, Object value) {
         userData.put(key, value);
     }
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/ui/CssClassUiEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/ui/CssClassUiEvent.java
index 7a10d94..a3ea0bf 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/ui/CssClassUiEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/ui/CssClassUiEvent.java
@@ -20,68 +20,70 @@ package org.apache.isis.applib.events.ui;
 
 import org.apache.isis.applib.annotation.DomainObjectLayout;
 
+import lombok.Getter;
+import lombok.Setter;
+
 /**
  * Emitted for subscribers to obtain a cssClass hint (equivalent to the <tt>cssClass()</tt> supporting method or the {@link DomainObjectLayout#cssClass()} attribute).
  */
+// tag::refguide[]
 public abstract class CssClassUiEvent<S> extends AbstractUiEvent<S> {
 
-    // -- constructors
-    /**
-     * If used then the framework will set state via (non-API) setters.
-     *
-     */
-    public CssClassUiEvent() {
-        this(null);
-    }
-
-    public CssClassUiEvent(final S source) {
-        super(source);
-    }
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObjectLayout#cssClassUiEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object-layout.css-class-ui-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends CssClassUiEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends CssClassUiEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends CssClassUiEvent<Object> {}
 
+    // end::refguide[]
 
-    // -- cssClass
-    private String cssClass;
+    /**
+     * If used then the framework will set state via (non-API) setters.
+     *
+     */
+    public CssClassUiEvent() {
+        this(null);
+    }
+
+    public CssClassUiEvent(final S source) {
+        super(source);
+    }
 
     /**
      * The CSS class as provided by a subscriber using {@link #setCssClass(String)}.
      */
-    public String getCssClass() {
-        return cssClass;
-    }
+    // tag::refguide[]
+    @Getter
+    private String cssClass;
 
+    // end::refguide[]
     /**
      * For subscribers to call to provide a CSS class for this object.
      */
+    // tag::refguide[]
     public void setCssClass(final String cssClass) {
         this.cssClass = cssClass;
     }
 
-
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/ui/LayoutUiEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/ui/LayoutUiEvent.java
index b267f5a..5804488 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/ui/LayoutUiEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/ui/LayoutUiEvent.java
@@ -22,71 +22,69 @@ import java.util.EventObject;
 
 import org.apache.isis.applib.annotation.DomainObjectLayout;
 
+import lombok.Getter;
+
 /**
  * Emitted for subscribers to obtain a layout hint (equivalent to the <tt>layout()</tt> supporting method).
  */
+// tag::refguide[]
 public abstract class LayoutUiEvent<S> extends AbstractUiEvent<S> {
 
-    //region > constructors
-    /**
-     * If used then the framework will set state via (non-API) setters.
-     *
-     * <p>
-     *     Because the {@link EventObject} superclass prohibits a null source, a dummy value is temporarily used.
-     * </p>
-     */
-    public LayoutUiEvent() {
-        this(null);
-    }
-
-    public LayoutUiEvent(final S source) {
-        super(source);
-    }
-
-    //endregion
-
-    //region > Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link DomainObjectLayout#layoutUiEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object-layout.layout-ui-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends LayoutUiEvent<Object> { }
-    //endregion
-
-    //region > Noop class
 
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends LayoutUiEvent<Object> { }
-    //endregion
-
-    //region > Doop class
 
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends LayoutUiEvent<Object> { }
-    //endregion
 
-    //region > layout
-    private String layout;
+    // end::refguide[]
+    /**
+     * If used then the framework will set state via (non-API) setters.
+     *
+     * <p>
+     *     Because the {@link EventObject} superclass prohibits a null source, a dummy value is temporarily used.
+     * </p>
+     */
+    public LayoutUiEvent() {
+        this(null);
+    }
+
+    public LayoutUiEvent(final S source) {
+        super(source);
+    }
 
     /**
      * The name of the alternate layout to use, as provided by a subscriber using {@link #setLayout(String)}.
      */
-    public String getLayout() {
-        return layout;
-    }
+    // tag::refguide[]
+    @Getter
+    private String layout;
 
+    // end::refguide[]
     /**
      * For subscribers to call to provide a layout for this object.
      */
+    // tag::refguide[]
     public void setLayout(final String layout) { }
-    //endregion
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/events/ui/TitleUiEvent.java b/api/applib/src/main/java/org/apache/isis/applib/events/ui/TitleUiEvent.java
index 617be2b..88e6829 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/events/ui/TitleUiEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/events/ui/TitleUiEvent.java
@@ -22,40 +22,42 @@ import java.util.EventObject;
 
 import org.apache.isis.applib.services.i18n.TranslatableString;
 
+import lombok.Getter;
+
 /**
  * Emitted for subscribers to obtain a cssClass hint (equivalent to the <tt>title()</tt> supporting method).
  */
+// tag::refguide[]
 public abstract class TitleUiEvent<S> extends AbstractUiEvent<S> {
 
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObjectLayout#titleUiEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object-layout.title-ui-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends TitleUiEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property seting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends TitleUiEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends TitleUiEvent<Object> {}
 
+    // end::refguide[]
 
-    // -- constructors
     /**
      * If used then the framework will set state via (non-API) setters.
      *
@@ -72,10 +74,6 @@ public abstract class TitleUiEvent<S> extends AbstractUiEvent<S> {
     }
 
 
-
-    // -- title
-    private String title;
-
     /**
      * The title as provided by a subscriber using {@link #setTitle(String)}.
      *
@@ -83,21 +81,21 @@ public abstract class TitleUiEvent<S> extends AbstractUiEvent<S> {
      *     Note that a {@link #getTranslatableTitle()} will be used in preference, if available.
      * </p>
      */
-    public String getTitle() {
-        return title;
-    }
+    // tag::refguide[]
+    @Getter
+    private String title;
 
+    // end::refguide[]
     /**
      * For subscribers to call to provide a (non-translated) title for this object.
      */
+    // tag::refguide[]
     public void setTitle(final String title) {
         this.title = title;
     }
 
 
-    // -- translatableTitle
-    private TranslatableString translatableTitle;
-
+    // end::refguide[]
     /**
      * The translatable (i18n) title as provided by a subscriber using {@link #setTranslatableTitle(TranslatableString)}.
      *
@@ -106,16 +104,19 @@ public abstract class TitleUiEvent<S> extends AbstractUiEvent<S> {
      *     {@link #getTitle() non-translatable title}.
      * </p>
      */
-    public TranslatableString getTranslatableTitle() {
-        return translatableTitle;
-    }
+    // tag::refguide[]
+    @Getter
+    private TranslatableString translatableTitle;
 
     /**
      * For subscribers to call to provide a translatable (i18n) title for this object.
      */
+    // tag::refguide[]
     public void setTranslatableTitle(final TranslatableString translatableTitle) {
         this.translatableTitle = translatableTitle;
     }
 
+    // tag::refguide[]
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/graph/Edge.java b/api/applib/src/main/java/org/apache/isis/applib/graph/Edge.java
index 1650f5b..bd4c0f3 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/graph/Edge.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/graph/Edge.java
@@ -25,9 +25,12 @@ package org.apache.isis.applib.graph;
  *
  * @param <T> type constraint for values contained by this edge's vertices
  */
+// tag::refguide[]
 public interface Edge<T> {
 
-    public Vertex<T> getFrom();
-    public Vertex<T> getTo();
+    Vertex<T> getFrom();
+
+    Vertex<T> getTo();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/graph/SimpleEdge.java b/api/applib/src/main/java/org/apache/isis/applib/graph/SimpleEdge.java
index 3eba78a..3ba7003 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/graph/SimpleEdge.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/graph/SimpleEdge.java
@@ -27,6 +27,7 @@ import lombok.Value;
  *
  * @param <T> type constraint for values contained by this edge's vertices
  */
+// tag::refguide[]
 @Value(staticConstructor = "of")
 public class SimpleEdge<T> implements Edge<T> {
 
@@ -34,3 +35,4 @@ public class SimpleEdge<T> implements Edge<T> {
     Vertex<T> to;
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/graph/Vertex.java b/api/applib/src/main/java/org/apache/isis/applib/graph/Vertex.java
index d2d09b0..58694f7 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/graph/Vertex.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/graph/Vertex.java
@@ -27,19 +27,16 @@ import java.util.stream.Stream;
  *
  * @param <T> type constraint for values contained by this vertex
  */
+// tag::refguide[]
 public interface Vertex<T> {
 
-    // -- VALUE
-
     public T getValue();
 
-    // -- EDGES
-
-    public int getIncomingCount();
-    public int getOutgoingCount();
-
-    public Stream<Edge<T>> streamIncoming();
-    public Stream<Edge<T>> streamOutgoing();
+    int getIncomingCount();
+    int getOutgoingCount();
 
+    Stream<Edge<T>> streamIncoming();
+    Stream<Edge<T>> streamOutgoing();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/jaxbadapters/PersistentEntitiesAdapter.java b/api/applib/src/main/java/org/apache/isis/applib/jaxbadapters/PersistentEntitiesAdapter.java
index 087d748..a463c8d 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/jaxbadapters/PersistentEntitiesAdapter.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/jaxbadapters/PersistentEntitiesAdapter.java
@@ -28,14 +28,19 @@ import org.apache.isis.applib.services.bookmark.Bookmark;
 import org.apache.isis.applib.services.bookmark.BookmarkService;
 import org.apache.isis.schema.common.v2.OidsDto;
 
+import lombok.AccessLevel;
+import lombok.Getter;
 import lombok.val;
 
+// tag::refguide[]
 public class PersistentEntitiesAdapter extends XmlAdapter<OidsDto, List<Object>> {
 
-    @Inject private BookmarkService bookmarkService;
-    
+    @Inject @Getter(AccessLevel.PROTECTED)
+    private BookmarkService bookmarkService;
+
     @Override
     public List<Object> unmarshal(final OidsDto oidsDto) {
+        // end::refguide[]
 
         List<Object> domainObjects = new ArrayList<>();
         for (val oidDto : oidsDto.getOid()) {
@@ -44,10 +49,15 @@ public class PersistentEntitiesAdapter extends XmlAdapter<OidsDto, List<Object>>
             domainObjects.add(domainObject);
         }
         return domainObjects;
+
+        // tag::refguide[]
+        // ...
     }
 
     @Override
     public OidsDto marshal(final List<Object> domainObjects) {
+        // end::refguide[]
+
         if(domainObjects == null) {
             return null;
         }
@@ -57,10 +67,10 @@ public class PersistentEntitiesAdapter extends XmlAdapter<OidsDto, List<Object>>
             oidsDto.getOid().add(bookmark.toOidDto());
         }
         return oidsDto;
-    }
 
-    protected BookmarkService getBookmarkService() {
-        return bookmarkService;
+        // tag::refguide[]
+        // ...
     }
-    
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/jaxbadapters/PersistentEntityAdapter.java b/api/applib/src/main/java/org/apache/isis/applib/jaxbadapters/PersistentEntityAdapter.java
index 67d2cef..5a2a99e 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/jaxbadapters/PersistentEntityAdapter.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/jaxbadapters/PersistentEntityAdapter.java
@@ -25,26 +25,35 @@ import org.apache.isis.schema.common.v2.OidDto;
 
 import lombok.val;
 
+// tag::refguide[]
 public class PersistentEntityAdapter extends XmlAdapter<OidDto, Object> {
 
     @Inject private BookmarkService bookmarkService;
-    
+
     @Override
     public Object unmarshal(final OidDto oidDto) throws Exception {
+        // end::refguide[]
 
         val bookmark = Bookmark.from(oidDto);
-
         return bookmarkService.lookup(bookmark);
+
+        // tag::refguide[]
+        // ...
     }
 
     @Override
     public OidDto marshal(final Object domainObject) throws Exception {
+        // end::refguide[]
+
         if(domainObject == null) {
             return null;
         }
         val bookmark = bookmarkService.bookmarkForElseThrow(domainObject);
         return bookmark.toOidDto();
+
+        // tag::refguide[]
+        // ...
     }
 
-    
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/query/Query.java b/api/applib/src/main/java/org/apache/isis/applib/query/Query.java
index c8ecc6e..02e6931 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/query/Query.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/query/Query.java
@@ -40,33 +40,45 @@ import org.apache.isis.applib.services.repository.RepositoryService;
  * <b>Note:</b> that not every object store will necessarily support this
  * interface. In particular, the in-memory object store does not. For this, you
  * can use the {@link Predicate} interface to similar effect, for example in
- * {@link RepositoryService#allMatches(Class, Predicate, long...)}).
+ * {@link RepositoryService#allMatches(Class, Predicate, long, long)}).
  *
  * Note that the predicate is applied within the {@link RepositoryService}
  * (ie client-side) rather than being pushed back to the object store.
  */
+// tag::refguide[]
 public interface Query<T> extends Serializable {
 
+    // end::refguide[]
     /**
      * The {@link Class} of the objects returned by this query.
      */
-    public Class<T> getResultType();
+    // tag::refguide[]
+    Class<T> getResultType();
 
+    // end::refguide[]
     /**
      * A human-readable representation of this query and its values.
      */
-    public String getDescription();
+    // tag::refguide[]
+    String getDescription();
 
+    // end::refguide[]
     /**
      * The start index into the set table
+     *
      * @return
      */
-    public long getStart();
-
+    // tag::refguide[]
+    long getStart();
 
+    // end::refguide[]
     /**
      * The number of items to return, starting at {@link #getStart()}
+     *
      * @return
      */
-    public long getCount();
+    // tag::refguide[]
+    long getCount();
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/security/RoleMemento.java b/api/applib/src/main/java/org/apache/isis/applib/security/RoleMemento.java
index f9802fd..a220a2b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/security/RoleMemento.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/security/RoleMemento.java
@@ -21,8 +21,12 @@ package org.apache.isis.applib.security;
 
 import org.apache.isis.applib.annotation.MemberOrder;
 
+import lombok.Getter;
+
+// tag::refguide[]
 public final class RoleMemento {
 
+    // end::refguide[]
     /**
      * Creates a new role with the specified name. Description is left blank.
      */
@@ -44,29 +48,18 @@ public final class RoleMemento {
         this.description = description;
     }
 
-    // {{ Identification
+    // tag::refguide[]
     public String title() {
         return name;
     }
 
-    // }}
-
-    // {{ Name
-    private final String name;
-
     @MemberOrder(sequence = "1.1")
-    public String getName() {
-        return name;
-    }
-
-    // }}
+    @Getter
+    private final String name;
 
-    // {{ Description
+    @MemberOrder(sequence = "1.2")
+    @Getter
     private final String description;
 
-    @MemberOrder(sequence = "1.2")
-    public String getDescription() {
-        return description;
-    }
-    // }}
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/security/UserMemento.java b/api/applib/src/main/java/org/apache/isis/applib/security/UserMemento.java
index 7b26047..bf3bb7a 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/security/UserMemento.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/security/UserMemento.java
@@ -25,13 +25,17 @@ import java.util.List;
 
 import org.apache.isis.applib.annotation.MemberOrder;
 
+import lombok.Getter;
+import lombok.experimental.UtilityClass;
+
 /**
  * Details, obtained from the container, about the user and his roles.
  * Read-only.
  */
+// tag::refguide[]
 public final class UserMemento {
 
-    // -- constructors
+    // end::refguide[]
     /**
      * Creates a new user with the specified name and no roles.
      */
@@ -57,44 +61,30 @@ public final class UserMemento {
         this.roles.addAll(roles);
     }
 
-
-    // -- title
+    // tag::refguide[]
     public String title() {
         return name;
     }
 
-
-
-    // -- name, NameType
-
-    // {{ (User) Name, isCurrentUser
-    private final String name;
-
+    // end::refguide[]
     /**
      * The user's login name.
      */
+    // tag::refguide[]
     @MemberOrder(sequence = "1.1")
-    public String getName() {
-        return name;
-    }
-
-    public static class NameType {
-
-        private NameType() {}
-
-        public static class Meta {
-
-            public static final int MAX_LEN = 50;
-
-            private Meta() {}
-
-        }
-
-    }
-
+    @Getter
+    private final String name;
 
+    // end::refguide[]
+    /**
+     * The roles associated with this user.
+     */
+    // tag::refguide[]
+    @Getter
+    @MemberOrder(sequence = "1.1")
+    private final List<RoleMemento> roles = new ArrayList<RoleMemento>();
 
-    // -- isCurrentUser
+    // end::refguide[]
     /**
      * Determine if the specified name is this user.
      *
@@ -109,19 +99,6 @@ public final class UserMemento {
         return name.equals(userName);
     }
 
-
-
-    // -- roles
-    private final List<RoleMemento> roles = new ArrayList<RoleMemento>();
-
-    /**
-     * The roles associated with this user.
-     */
-    @MemberOrder(sequence = "1.1")
-    public List<RoleMemento> getRoles() {
-        return roles;
-    }
-
     /**
      * Determines if the user fulfills the specified role.
      *
@@ -144,9 +121,6 @@ public final class UserMemento {
         return false;
     }
 
-
-
-    // -- toString
     @Override
     public String toString() {
         final StringBuilder buf = new StringBuilder();
@@ -156,6 +130,15 @@ public final class UserMemento {
         return "User [name=" + getName() + ",roles=" + buf.toString() + "]";
     }
 
+    @UtilityClass
+    public static class NameType {
+        @UtilityClass
+        public static class Meta {
+            public static final int MAX_LEN = 50;
+        }
+    }
 
+    // tag::refguide[]
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/HasUniqueId.java b/api/applib/src/main/java/org/apache/isis/applib/services/HasUniqueId.java
index 6dc058d..57245db 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/HasUniqueId.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/HasUniqueId.java
@@ -26,11 +26,15 @@ import java.util.UUID;
  * and so can be associated together using a unique identifier.
  *
  */
+// tag::refguide[]
 public interface HasUniqueId {
 
+    // end::refguide[]
     /**
      * The unique identifier (a GUID) of the request/interaction/transaction.
      */
+    // tag::refguide[]
     UUID getUniqueId();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/HasUsername.java b/api/applib/src/main/java/org/apache/isis/applib/services/HasUsername.java
index dbdf815..7f7a240 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/HasUsername.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/HasUsername.java
@@ -26,8 +26,10 @@ package org.apache.isis.applib.services;
  * Other services can then use this username as a means to contributed actions/collections to render such additional
  * information relating to the activities of the user.
  */
+// tag::refguide[]
 public interface HasUsername {
 
-    public String getUsername();
+    String getUsername();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/WithTransactionScope.java b/api/applib/src/main/java/org/apache/isis/applib/services/WithTransactionScope.java
index befeaa1..c066b22 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/WithTransactionScope.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/WithTransactionScope.java
@@ -25,6 +25,8 @@ package org.apache.isis.applib.services;
  *
  * TODO: We ought instead to use Spring's @TransactionScope rather than roll-our-own.
  */
+// tag::refguide[]
 public interface WithTransactionScope {
     void resetForNextTransaction();
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/metrics/MetricsService.java b/api/applib/src/main/java/org/apache/isis/applib/services/metrics/MetricsService.java
index 103621b..633610f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/metrics/MetricsService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/metrics/MetricsService.java
@@ -24,6 +24,7 @@ import org.apache.isis.schema.ixn.v2.MemberExecutionDto;
 // tag::refguide[]
 public interface MetricsService {
 
+    // end::refguide[]
     /**
      * The number of objects that have, so far in this request, been loaded from the database.
      *
@@ -35,8 +36,10 @@ public interface MetricsService {
      *     Is captured within {@link MemberExecutionDto#getMetrics()} (accessible from {@link InteractionContext#getInteraction()}).
      * </p>
      */
+    // tag::refguide[]
     int numberObjectsLoaded();
 
+    // end::refguide[]
     /**
      * The number of objects that have, so far in this request, been dirtied/will need updating in the database); a
      * good measure of the footprint of the interaction.
@@ -49,6 +52,7 @@ public interface MetricsService {
      *     Is captured within {@link MemberExecutionDto#getMetrics()} (accessible from {@link InteractionContext#getInteraction()}).
      * </p>
      */
+    // tag::refguide[]
     int numberObjectsDirtied();
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/publish/PublishedObjects.java b/api/applib/src/main/java/org/apache/isis/applib/services/publish/PublishedObjects.java
index c97656b..ebc2fcd 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/publish/PublishedObjects.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/publish/PublishedObjects.java
@@ -33,11 +33,8 @@ public interface PublishedObjects extends HasUniqueId, HasUsername {
     ChangesDto getDto();
 
     int getNumberLoaded();
-
     int getNumberCreated();
-
     int getNumberUpdated();
-
     int getNumberDeleted();
 
     int getNumberPropertiesModified();
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/publish/PublisherService.java b/api/applib/src/main/java/org/apache/isis/applib/services/publish/PublisherService.java
index 6e7f798..dea94e0 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/publish/PublisherService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/publish/PublisherService.java
@@ -29,11 +29,13 @@ import org.apache.isis.applib.util.schema.InteractionDtoUtils;
 // tag::refguide[]
 public interface PublisherService {
 
+    // end::refguide[]
     /**
      * Most implementations are expected to use {@link Interaction.Execution#getDto()} to create a serializable
      * XML representation of the execution.  The easiest way to do this is using {@link InteractionDtoUtils#newInteractionDto(Interaction.Execution)}.  There is
      * some flexibility here, though.
      */
+    // tag::refguide[]
     void publish(final Interaction.Execution<?, ?> execution);
 
     void publish(final PublishedObjects publishedObjects);
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/queryresultscache/QueryResultsCache.java b/api/applib/src/main/java/org/apache/isis/applib/services/queryresultscache/QueryResultsCache.java
index 323869b..6b815b5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/queryresultscache/QueryResultsCache.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/queryresultscache/QueryResultsCache.java
@@ -66,8 +66,8 @@ public interface QueryResultsCache {
     
     void resetForNextTransaction();
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     class Key {
 
         @Getter
@@ -77,6 +77,7 @@ public interface QueryResultsCache {
         @Getter
         private final Object[] keys;
 
+        // end::refguide-1[]
         public Key(Class<?> callingClass, String methodName, Object... keys) {
             this.callingClass = callingClass;
             this.methodName = methodName;
@@ -129,16 +130,17 @@ public interface QueryResultsCache {
         public String toString() {
             return callingClass.getName() + "#" + methodName  + Arrays.toString(keys);
         }
+        // tag::refguide-1[]
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide-2[]
+    // tag::refguide-2[]
     @Data
     class Value<T> {
         private final T result;
     }
-// end::refguide-2[]
+    // end::refguide-2[]
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/registry/ServiceRegistry.java b/api/applib/src/main/java/org/apache/isis/applib/services/registry/ServiceRegistry.java
index ca8fbff..45972aa 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/registry/ServiceRegistry.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/registry/ServiceRegistry.java
@@ -52,6 +52,7 @@ public interface ServiceRegistry {
      * @param qualifiers
      * @return non-null
      */
+    // tag::refguide[]
     <T> Can<T> select(Class<T> type, Annotation[] qualifiers);
 
     /**
@@ -60,36 +61,54 @@ public interface ServiceRegistry {
      * @param type
      * @return non-null
      */
+    // tag::refguide[]
     default <T> Can<T> select(final Class<T> type){
+        // end::refguide[]
+
         return select(type, _Constants.emptyAnnotations);
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * Streams all registered bean adapters implementing the requested type.
      */
+    // tag::refguide[]
     default Stream<ManagedBeanAdapter> streamRegisteredBeansOfType(Class<?> requiredType) {
+        // end::refguide[]
+
         return streamRegisteredBeans()
                 .filter(beanAdapter->beanAdapter.isCandidateFor(requiredType));
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * Returns all bean adapters that have been registered.
      */
+    // tag::refguide[]
     Stream<ManagedBeanAdapter> streamRegisteredBeans();
 
+    // end::refguide[]
     /**
      * Returns a registered bean of given {@code name}.
      *
      * @param id - corresponds to the ObjectSpecificationId of the bean's type
      */
+    // tag::refguide[]
     Optional<ManagedBeanAdapter> lookupRegisteredBeanById(String id);
 
-
+    // end::refguide[]
     /**
      * Returns a registered bean of given {@code name}, or throws when no such bean.
      *
      * @param id - corresponds to the ObjectSpecificationId of the bean's type
      */
+    // tag::refguide[]
     default ManagedBeanAdapter lookupRegisteredBeanByIdElseFail(String id) {
         return lookupRegisteredBeanById(id).orElseThrow(
                 ()->_Exceptions.unrecoverable(
@@ -98,14 +117,17 @@ public interface ServiceRegistry {
 
     Optional<?> lookupBeanById(final String id);
 
+    // end::refguide[]
     /**
      * Returns a domain service implementing the requested type.
      * <p>
      * If this lookup is ambiguous, the service annotated with highest priority is returned.
      * see {@link Priority}
      */
+    // tag::refguide[]
     default <T> Optional<T> lookupService(final Class<T> serviceClass) {
-// end::refguide[]
+        // end::refguide[]
+
         val bin = select(serviceClass);
         if(bin.isEmpty()) {
             return Optional.empty();
@@ -123,20 +145,25 @@ public interface ServiceRegistry {
         bin.forEach(toMaxPrioReduction);
 
         return toMaxPrioReduction.getResult();
-// tag::refguide[]
+
+        // tag::refguide[]
         // ...
     }
 
     default <T> T lookupServiceElseFail(final Class<T> serviceClass) {
+        // end::refguide[]
+
         return lookupService(serviceClass)
                 .orElseThrow(()->
                 new NoSuchElementException("Could not locate service of type '" + serviceClass + "'"));
+
+        // tag::refguide[]
+        // ...
     }
+    // end::refguide[]
 
     // -- PRIORITY ANNOTATION HANDLING
 
-// end::refguide[]
-// tag::refguide-1[]
     class InstanceByPriorityComparator implements Comparator<Object> {
 
         private static final InstanceByPriorityComparator INSTANCE =
@@ -172,8 +199,7 @@ public interface ServiceRegistry {
         }
 
     }
-// end::refguide-1[]
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/repository/EntityState.java b/api/applib/src/main/java/org/apache/isis/applib/services/repository/EntityState.java
index c48a974..26ed267 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/repository/EntityState.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/repository/EntityState.java
@@ -31,25 +31,23 @@ public enum EntityState {
     not_Persistable,
     persistable_Attached,
     persistable_Detached,
-    persistable_Destroyed
-
+    persistable_Destroyed,
+    // end::refguide[]
     ;
 
     public boolean isPersistable() {
         return this != not_Persistable;
     }
-
     public boolean isAttached() {
         return this == persistable_Attached;
     }
-
     public boolean isDetached() {
         return this == persistable_Detached;
     }
-
     public boolean isDestroyed() {
         return this == persistable_Destroyed;
     }
 
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/repository/RepositoryService.java b/api/applib/src/main/java/org/apache/isis/applib/services/repository/RepositoryService.java
index ba39a0a..237b417 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/repository/RepositoryService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/repository/RepositoryService.java
@@ -32,55 +32,70 @@ import lombok.val;
 // tag::refguide[]
 public interface RepositoryService {
 
+    // end::refguide[]
     /**
      * Returns the EntityState of given {@code object}. Returns {@link EntityState#not_Persistable} for {@code object==null}.
      * @param object
      * @return (non-null)
      * @since 2.0
      */
+    // tag::refguide[]
     EntityState getEntityState(@Nullable Object object);
 
+    // end::refguide[]
     /**
      * Same as {@link org.apache.isis.applib.services.factory.FactoryService#detachedEntity(Class)}; provided as a
      * convenience because instantiating and {@link #persist(Object) persisting} are often done together.
      * @since 2.0
      */
+    // tag::refguide[]
     <T> T detachedEntity(Class<T> ofType);
 
+    // end::refguide[]
     /**
      * Persist the specified object (or do nothing if already persistent).
      *
      * @see #isPersistent(Object)
      */
+    // tag::refguide[]
     <T> T persist(T domainObject);
 
+    // end::refguide[]
     /**
      * Persist the specified object (or do nothing if already persistent) and flushes changes to the database.
      *
      * @see #persist(Object)
      */
+    // tag::refguide[]
     <T> T persistAndFlush(T domainObject);
 
+    // end::refguide[]
     /**
      * Deletes the domain object but only if is attached.
      *
      * @param domainObject
      */
+    // tag::refguide[]
     void remove(Object domainObject);
 
+    // end::refguide[]
     /**
      * Deletes the domain object but only if is persistent, and flushes changes to the database.
      *
      * @param domainObject
      */
+    // tag::refguide[]
     void removeAndFlush(Object domainObject);
 
+    // end::refguide[]
     /**
      * As {@link #allInstances(Class, long, long)}, but but returning all instances rather than just those
      *      * within the specified range..
      */
+    // tag::refguide[]
     <T> List<T> allInstances(Class<T> ofType);
 
+    // end::refguide[]
     /**
      * Returns all the instances of the specified type (including subtypes).
      * If the optional range parameters are used, the dataset returned starts
@@ -105,14 +120,18 @@ public interface RepositoryService {
      * @param <T>
      * @return
      */
+    // tag::refguide[]
     <T> List<T> allInstances(Class<T> ofType, long start, long count);
 
+    // end::refguide[]
     /**
      * As {@link #allMatches(Class, Predicate, long, long)}, but returning all instances rather than just those
      * within the specified range.
      */
+    // tag::refguide[]
     <T> List<T> allMatches(Class<T> ofType, Predicate<? super T> predicate);
 
+    // end::refguide[]
     /**
      * Returns all the instances of the specified type (including subtypes) that
      * the predicate object accepts. If the optional range parameters are used, the
@@ -139,8 +158,10 @@ public interface RepositoryService {
      * @param <T>
      * @return
      */
+    // tag::refguide[]
     <T> List<T> allMatches(Class<T> ofType, Predicate<? super T> predicate, long start, long count);
 
+    // end::refguide[]
     /**
      * Returns all the instances that match the given {@link Query}.
      *
@@ -155,8 +176,10 @@ public interface RepositoryService {
      *     This method is the recommended way of querying for multiple instances.
      * </p>
      */
+    // tag::refguide[]
     <T> List<T> allMatches(Query<T> query);
 
+    // end::refguide[]
     /**
      * Find the only instance of the specified type (including subtypes) that
      * has the specified title.
@@ -171,8 +194,10 @@ public interface RepositoryService {
      * instances.  Use {@link #uniqueMatch(Query)} for production code.
      * </p>
      */
+    // tag::refguide[]
     <T> Optional<T> uniqueMatch(Class<T> ofType, Predicate<T> predicate);
 
+    // end::refguide[]
     /**
      * Find the only instance that matches the provided query.
      *
@@ -187,8 +212,10 @@ public interface RepositoryService {
      *
      * @see #firstMatch(Query)
      */
+    // tag::refguide[]
     <T> Optional<T> uniqueMatch(Query<T> query);
 
+    // end::refguide[]
     /**
      * Find the only instance of the specified type (including subtypes) that
      * has the specified title.
@@ -203,8 +230,10 @@ public interface RepositoryService {
      * instances.  Use {@link #firstMatch(Query)} for production code.
      * </p>
      */
+    // tag::refguide[]
     <T> Optional<T> firstMatch(Class<T> ofType, Predicate<T> predicate);
 
+    // end::refguide[]
     /**
      * Find the only instance that matches the provided query, if any..
      *
@@ -215,8 +244,9 @@ public interface RepositoryService {
      *
      * @see #firstMatch(Query)
      */
+    // tag::refguide[]
     <T> Optional<T> firstMatch(Query<T> query);
-// end::refguide[]
+    // end::refguide[]
 
     // -- DEPRECATIONS
 
@@ -254,6 +284,7 @@ public interface RepositoryService {
         return entityState.isDestroyed();
     }
 
-// tag::refguide[]
+    // tag::refguide[]
+
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/routing/RoutingService.java b/api/applib/src/main/java/org/apache/isis/applib/services/routing/RoutingService.java
index 6ec398d..a4574b3 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/routing/RoutingService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/routing/RoutingService.java
@@ -27,7 +27,6 @@ import org.apache.isis.applib.annotation.Programmatic;
 public interface RoutingService {
 
     boolean canRoute(Object original);
-
     Object route(Object original);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/scratchpad/Scratchpad.java b/api/applib/src/main/java/org/apache/isis/applib/services/scratchpad/Scratchpad.java
index 02afebe..a8dbd20 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/scratchpad/Scratchpad.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/scratchpad/Scratchpad.java
@@ -55,7 +55,7 @@ import lombok.extern.log4j.Log4j2;
 @Log4j2
 public class Scratchpad {
 
-// end::refguide[]
+    // end::refguide[]
     public Scratchpad(){
         log.debug("init");
     }
@@ -70,29 +70,37 @@ public class Scratchpad {
         log.debug("preDestroy");
     }
 
-// tag::refguide[]
+    // end::refguide[]
     /**
      * Provides a mechanism for each object being acted upon to pass
      * data to the next object.
      */
+    // tag::refguide[]
     private final Map<Object, Object> userData = _Maps.newHashMap();
 
+    // end::refguide[]
     /**
      * Obtain user-data, as set by a previous object being acted upon.
      */
+    // tag::refguide[]
     public Object get(Object key) {
         return userData.get(key);
     }
+
+    // end::refguide[]
     /**
      * Set user-data, for the use of a subsequent object being acted upon.
      */
+    // tag::refguide[]
     public void put(Object key, Object value) {
         userData.put(key, value);
     }
 
+    // end::refguide[]
     /**
      * Clear any user data.
      */
+    // tag::refguide[]
     public void clear() {
         userData.clear();
     }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/session/SessionLoggingService.java b/api/applib/src/main/java/org/apache/isis/applib/services/session/SessionLoggingService.java
index 7260ae0..31acc4e 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/session/SessionLoggingService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/session/SessionLoggingService.java
@@ -41,10 +41,9 @@ public interface SessionLoggingService {
     }
 
     void log(Type type, String username, Date date, CausedBy causedBy, String sessionId);
+    // end::refguide[]
 
-// end::refguide[]
-
-// tag::refguide-1[]
+    // tag::refguide-1[]
     class Stderr implements SessionLoggingService {
 
         @Override
@@ -65,7 +64,9 @@ public interface SessionLoggingService {
             System.err.println(logMessage);
         }
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-1[]
+
+    // tag::refguide[]
+
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/sudo/SudoService.java b/api/applib/src/main/java/org/apache/isis/applib/services/sudo/SudoService.java
index 335c5d5..afbbad5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/sudo/SudoService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/sudo/SudoService.java
@@ -27,51 +27,64 @@ import org.apache.isis.applib.services.user.UserService;
 
 /**
  * Intended only for use by fixture scripts and integration tests, allows a block of code to execute
- * while the {@link org.apache.isis.applib.DomainObjectContainer container}'s
- * {@link UserService#getUser() getUser()} method returns the specified user/role as the effective user.
+ * while the {@link UserService}'s {@link UserService#getUser() getUser()} method returns the specified user/role
+ * as the effective user.
  */
 // tag::refguide[]
 public interface SudoService {
 
+    // end::refguide[]
     /**
      * If included in the list of roles, then will disable security checks (can view and use all object members).
      */
+    // tag::refguide[]
     String ACCESS_ALL_ROLE = SudoService.class.getName() + "#accessAll";
 
+    // end::refguide[]
     /**
-     * Executes the supplied block, with the {@link DomainObjectContainer} returning the specified user.
+     * Executes the supplied block, with the {@link UserService} returning the specified user.
      *
      * <p>
      *    The roles of this user will be the same as the currently logged-in user.
      * </p>
      */
+    // tag::refguide[]
     void sudo(String username, final Runnable runnable);
 
+    // end::refguide[]
     /**
-     * Executes the supplied block, with the {@link DomainObjectContainer} returning the specified user.
+     * Executes the supplied block, with the {@link UserService} returning the specified user.
      *
      * <p>
      *    The roles of this user will be the same as the currently logged-in user.
      * </p>
      */
+    // tag::refguide[]
     <T> T sudo(String username, final Callable<T> callable);
 
+    // end::refguide[]
     /**
-     * Executes the supplied block, with the {@link DomainObjectContainer} returning the specified user with the specified roles.
+     * Executes the supplied block, with the {@link UserService} returning the specified user with the specified roles.
      */
+    // tag::refguide[]
     void sudo(String username, List<String> roles, final Runnable runnable);
 
+    // end::refguide[]
     /**
-     * Executes the supplied block, with the {@link DomainObjectContainer} returning the specified user with the specified roles.
+     * Executes the supplied block, with the {@link UserService} returning the specified user with the specified roles.
      */
+    // tag::refguide[]
     <T> T sudo(String username, List<String> roles, final Callable<T> callable);
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+
+    // tag::refguide-1[]
     /**
      * Allows the {@link SudoService} to notify other services/components that the effective user has been changed.
      */
     interface Spi {
+
+        // end::refguide-1[]
         /**
          * Any implementation of the {@link SudoService} should call this method on all implementations of the
          * {@link Spi} service whenever {@link SudoService#sudo(String, List, Callable)} (or its overloads)
@@ -81,15 +94,14 @@ public interface SudoService {
          *     Modelled after Shiro security's <a href="https://shiro.apache.org/static/1.2.6/apidocs/org/apache/shiro/subject/Subject.html#runAs-org.apache.shiro.subject.PrincipalCollection-">runAs</a> support.
          * </p>
          */
-        @Programmatic
+        // tag::refguide-1[]
         void runAs(String username, List<String> roles);
 
-        /**
-         *
-         */
         void releaseRunAs();
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-1[]
+
+    // tag::refguide[]
+
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java b/api/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java
index 17b7150..15ba710 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/swagger/SwaggerService.java
@@ -28,9 +28,11 @@ import org.apache.isis.applib.annotation.ViewModel;
 // tag::refguide[]
 public interface SwaggerService {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide[]
     enum Visibility {
+
+        // end::refguide[]
         /**
          * Specification for use by third-party clients, ie public use.
          *
@@ -39,7 +41,10 @@ public interface SwaggerService {
          * of {@link NatureOfService#VIEW_REST_ONLY}.
          * </p>
          */
+        // tag::refguide[]
         PUBLIC,
+
+        // end::refguide[]
         /**
          * Specification for use only by internally-managed clients, ie private internal use.
          *
@@ -48,23 +53,28 @@ public interface SwaggerService {
          * </p>
          */
         PRIVATE,
+
+        // end::refguide[]
         /**
          * As {@link #PRIVATE}, also including any prototype actions (where {@link Action#restrictTo()} set to
          * {@link RestrictTo#PROTOTYPING}).
          */
-        PRIVATE_WITH_PROTOTYPING;
+        PRIVATE_WITH_PROTOTYPING
+        // end::refguide[]
+        ;
 
         public boolean isPublic() {
             return this == PUBLIC;
         }
+        // tag::refguide[]
+
     }
-// end::refguide-1[]
-// tag::refguide[]
 
     enum Format {
         JSON,
-        YAML;
-// end::refguide[]
+        YAML
+        // end::refguide[]
+        ;
         /**
          * Implementation note: not using subclasses, otherwise the key in translations.po becomes more complex.
          */
@@ -75,7 +85,7 @@ public interface SwaggerService {
                 return "application/yaml";
             }
         }
-// tag::refguide[]
+        // tag::refguide[]
     }
 
     String generateSwaggerSpec(final Visibility visibility, final Format format);
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/tablecol/TableColumnOrderService.java b/api/applib/src/main/java/org/apache/isis/applib/services/tablecol/TableColumnOrderService.java
index e2586d3..3c73edc 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/tablecol/TableColumnOrderService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/tablecol/TableColumnOrderService.java
@@ -42,8 +42,5 @@ public interface TableColumnOrderService {
             final Class<?> collectionType,
             final List<String> propertyIds);
 
-// end::refguide[]
-    // tag::refguide[]
-
 }
 // end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/title/TitleService.java b/api/applib/src/main/java/org/apache/isis/applib/services/title/TitleService.java
index 3b5ab71..38e4e6f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/title/TitleService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/title/TitleService.java
@@ -22,16 +22,20 @@ package org.apache.isis.applib.services.title;
 // tag::refguide[]
 public interface TitleService {
 
+    // end::refguide[]
     /**
      * Return the title of the object, as rendered in the UI by the
      * Isis viewers.
      */
+    // tag::refguide[]
     String titleOf(Object domainObject);
 
+    // end::refguide[]
     /**
      * Return the icon name of the object, as rendered in the UI by the
      * Isis viewers.
      */
+    // tag::refguide[]
     String iconNameOf(Object domainObject);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/urlencoding/UrlEncodingService.java b/api/applib/src/main/java/org/apache/isis/applib/services/urlencoding/UrlEncodingService.java
index 3a2e053..219d9f9 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/urlencoding/UrlEncodingService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/urlencoding/UrlEncodingService.java
@@ -29,6 +29,7 @@ public interface UrlEncodingService extends EncoderDecoder {
 
     @Override
     String encode(final byte[] bytes);
+
     @Override
     byte[] decode(String str);
 
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/user/UserService.java b/api/applib/src/main/java/org/apache/isis/applib/services/user/UserService.java
index 73682c2..5a6e855 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/user/UserService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/user/UserService.java
@@ -24,9 +24,11 @@ import org.apache.isis.applib.security.UserMemento;
 // tag::refguide[]
 public interface UserService {
 
+    // end::refguide[]
     /**
      * Get the details about the current user.
      */
+    // tag::refguide[]
     UserMemento getUser();
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/userprof/UserProfileService.java b/api/applib/src/main/java/org/apache/isis/applib/services/userprof/UserProfileService.java
index e4934fa..57a7415 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/userprof/UserProfileService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/userprof/UserProfileService.java
@@ -31,6 +31,7 @@ import org.apache.isis.applib.annotation.Programmatic;
 // tag::refguide[]
 public interface UserProfileService {
 
+    // end::refguide[]
     /**
      * Used as the menu name of the {@link org.apache.isis.applib.annotation.DomainServiceLayout.MenuBar#TERTIARY tertiary}
      * &quot;Me&quot; menu bar.
@@ -39,6 +40,7 @@ public interface UserProfileService {
      *     If returns <tt>null</tt>, then the current user name is used instead.
      * </p>
      */
+    // tag::refguide[]
     String userProfileName();
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/userreg/EmailNotificationService.java b/api/applib/src/main/java/org/apache/isis/applib/services/userreg/EmailNotificationService.java
index 3d1a859..1e118b1 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/userreg/EmailNotificationService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/userreg/EmailNotificationService.java
@@ -35,18 +35,18 @@ import org.apache.isis.applib.services.userreg.events.PasswordResetEvent;
  * </p>
  */
 // tag::refguide[]
-public interface EmailNotificationService extends Serializable {
-
-    @PostConstruct
-    void init() ;
+public interface EmailNotificationService
+                            extends Serializable {
 
     boolean send(EmailRegistrationEvent ev);
 
     boolean send(PasswordResetEvent ev);
 
+    // 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/userreg/UserDetails.java b/api/applib/src/main/java/org/apache/isis/applib/services/userreg/UserDetails.java
index 2e1f642..167a599 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/userreg/UserDetails.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/userreg/UserDetails.java
@@ -27,7 +27,8 @@ import lombok.Setter;
  * A model object for the signup page
  */
 // tag::refguide[]
-public class UserDetails implements Serializable {
+public class UserDetails
+                implements Serializable {
 
     private static final long serialVersionUID = -7308102332765149525L;
 
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/WrapperFactory.java b/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/WrapperFactory.java
index 494215a..e903e32 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/WrapperFactory.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/WrapperFactory.java
@@ -29,6 +29,7 @@ import org.apache.isis.core.commons.collections.ImmutableEnumSet;
 
 import lombok.AccessLevel;
 import lombok.RequiredArgsConstructor;
+import lombok.experimental.UtilityClass;
 
 /**
  * Provides the ability to &quot;wrap&quot; of a domain object such that it can
@@ -71,67 +72,85 @@ import lombok.RequiredArgsConstructor;
 // tag::refguide[]
 public interface WrapperFactory {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
     /**
      * Whether interactions with the wrapper are actually passed onto the
      * underlying domain object.
      *
-     * @see WrapperFactory#wrap(Object, ExecutionMode)
+     * @see WrapperFactory#wrap(Object, ImmutableEnumSet)
      */
+    // tag::refguide-1[]
     @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
     enum ExecutionMode {
 
+        // end::refguide-1[]
         /**
          * Skip all business rules.
          */
+        // tag::refguide-1[]
         SKIP_RULE_VALIDATION,
 
+        // end::refguide-1[]
         /**
          * Skip execution.
          */
+        // tag::refguide-1[]
         SKIP_EXECUTION,
 
+        // end::refguide-1[]
         /**
          * Don't fail fast, swallow any exception during validation or execution.
          */
+        // tag::refguide-1[]
         SWALLOW_EXCEPTIONS,
 
-        ;
+    }
+    // end::refguide-1[]
 
-        // -- PRESET ENUM SETS
+    // tag::refguide-2[]
+    @UtilityClass
+    class ExecutionModes {
 
+        // end::refguide-2[]
         /**
          * Validate all business rules and then execute. May throw exceptions in order to fail fast.
          */
+        // tag::refguide-2[]
         public static final ImmutableEnumSet<ExecutionMode> EXECUTE = ImmutableEnumSet.noneOf(ExecutionMode.class);
 
+        // end::refguide-2[]
         /**
          * Skip all business rules and then execute, does throw an exception if execution fails.
          */
-        public static final ImmutableEnumSet<ExecutionMode> SKIP_RULES = ImmutableEnumSet.of(SKIP_RULE_VALIDATION);
+        // tag::refguide-2[]
+        public static final ImmutableEnumSet<ExecutionMode> SKIP_RULES = ImmutableEnumSet.of(ExecutionMode.SKIP_RULE_VALIDATION);
 
+        // end::refguide-2[]
         /**
          * Validate all business rules but do not execute, throw an exception if validation
          * fails.
          */
-        public static final ImmutableEnumSet<ExecutionMode> NO_EXECUTE = ImmutableEnumSet.of(SKIP_EXECUTION);
+        // tag::refguide-2[]
+        public static final ImmutableEnumSet<ExecutionMode> NO_EXECUTE = ImmutableEnumSet.of(ExecutionMode.SKIP_EXECUTION);
 
+        // end::refguide-2[]
         /**
          * Validate all business rules and then execute, but don't throw an exception if validation
          * or execution fails.
          */
-        public static final ImmutableEnumSet<ExecutionMode> TRY = ImmutableEnumSet.of(SWALLOW_EXCEPTIONS);
+        // tag::refguide-2[]
+        public static final ImmutableEnumSet<ExecutionMode> TRY = ImmutableEnumSet.of(ExecutionMode.SWALLOW_EXCEPTIONS);
 
+        // end::refguide-2[]
         /**
          * Skips all steps.
          * @since 2.0
          */
-        public static final ImmutableEnumSet<ExecutionMode> NOOP = ImmutableEnumSet.of(SKIP_RULE_VALIDATION, SKIP_EXECUTION);
+        // tag::refguide-2[]
+        public static final ImmutableEnumSet<ExecutionMode> NOOP = ImmutableEnumSet.of(ExecutionMode.SKIP_RULE_VALIDATION, ExecutionMode.SKIP_EXECUTION);
 
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-2[]
 
     /**
      * Provides the &quot;wrapper&quot; of the underlying domain object.
@@ -140,31 +159,41 @@ public interface WrapperFactory {
      * If the object has (see {@link #isWrapper(Object)} already been wrapped),
      * then should just return the object back unchanged.
      */
+    // tag::refguide[]
     <T> T wrap(T domainObject);
 
+    // end::refguide[]
     /**
      * {@link #wrap(Object) wraps} a {@link FactoryService#mixin(Class, Object) mixin}.
      */
+    // tag::refguide[]
     <T> T wrapMixin(Class<T> mixinClass, Object mixedIn);
 
+    // end::refguide[]
     /**
-     * Convenience method for {@link #wrap(Object, ExecutionMode)} with {@link ExecutionMode#TRY},
+     * Convenience method for {@link #wrap(Object, ImmutableEnumSet)} with {@link ExecutionModes#TRY},
      * to make this feature more discoverable.
      */
+    // tag::refguide[]
     <T> T wrapTry(T domainObject);
 
+    // end::refguide[]
     /**
-     * Convenience method for {@link #wrap(Object, ExecutionMode)} with {@link ExecutionMode#NO_EXECUTE},
+     * Convenience method for {@link #wrap(Object, ImmutableEnumSet)} with {@link ExecutionModes#NO_EXECUTE},
      * to make this feature more discoverable.
      */
+    // tag::refguide[]
     <T> T wrapNoExecute(T domainObject);
 
+    // end::refguide[]
     /**
-     * Convenience method for {@link #wrap(Object, ExecutionMode)} with {@link ExecutionMode#SKIP_RULES},
+     * Convenience method for {@link #wrap(Object, ImmutableEnumSet)} with {@link ExecutionModes#SKIP_RULES},
      * to make this feature more discoverable.
      */
+    // tag::refguide[]
     <T> T wrapSkipRules(T domainObject);
 
+    // end::refguide[]
     /**
      * Same as {@link #wrap(Object)}, except the actual execution occurs only if
      * the <tt>execute</tt> parameter indicates.
@@ -173,9 +202,10 @@ public interface WrapperFactory {
      * Otherwise, will do all the validations (raise exceptions as required
      * etc.), but doesn't modify the model.
      */
+    // tag::refguide[]
     <T> T wrap(T domainObject, ImmutableEnumSet<ExecutionMode> mode);
 
-
+    // end::refguide[]
     /**
      * Obtains the underlying domain object, if wrapped.
      *
@@ -183,9 +213,10 @@ public interface WrapperFactory {
      * If the object {@link #isWrapper(Object) is not wrapped}, then
      * should just return the object back unchanged.
      */
+    // tag::refguide[]
     <T> T unwrap(T possibleWrappedDomainObject);
 
-
+    // end::refguide[]
     /**
      * Whether the supplied object has been wrapped.
      *
@@ -194,9 +225,14 @@ public interface WrapperFactory {
      *            - object that might or might not be a wrapper.
      * @return
      */
+    // tag::refguide[]
     <T> boolean isWrapper(T possibleWrappedDomainObject);
 
+    // end::refguide[]
+
+    //
     // -- ASYNC WRAPPING
+    //
 
     /**
      * Returns a {@link AsyncWrap} bound to the provided {@code domainObject},
@@ -208,20 +244,29 @@ public interface WrapperFactory {
      *
      * @since 2.0
      */
+    // tag::refguide[]
     <T> AsyncWrap<T> async(T domainObject, ImmutableEnumSet<ExecutionMode> mode);
 
+    // end::refguide[]
     /**
-     * Shortcut for {@link #async(Object, EnumSet)} using execution mode
-     * {@link ExecutionMode#EXECUTE}.
+     * Shortcut for {@link #async(Object, ImmutableEnumSet)} using execution mode
+     * {@link ExecutionModes#EXECUTE}.
      * @param <T>
      * @param domainObject
      *
      * @since 2.0
      */
+    // tag::refguide[]
     default <T> AsyncWrap<T> async(T domainObject) {
-        return async(domainObject, ExecutionMode.EXECUTE);
+        // end::refguide[]
+
+        return async(domainObject, ExecutionModes.EXECUTE);
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * Returns a {@link AsyncWrap} bound to the provided {@code mixinClass},
      * to prepare for type-safe asynchronous action execution.
@@ -233,29 +278,43 @@ public interface WrapperFactory {
      *
      * @since 2.0
      */
+    // tag::refguide[]
     <T> AsyncWrap<T> asyncMixin(Class<T> mixinClass, Object mixedIn, ImmutableEnumSet<ExecutionMode> mode);
 
+    // end::refguide[]
     /**
-     * Shortcut for {@link #asyncMixin(Class, Object, EnumSet)} using execution mode
-     * {@link ExecutionMode#EXECUTE}.
+     * Shortcut for {@link #asyncMixin(Class, Object, ImmutableEnumSet)} using execution mode
+     * {@link ExecutionModes#EXECUTE}.
      * @param <T>
      * @param mixinClass
      * @param mixedIn
      *
      * @since 2.0
      */
+    // tag::refguide[]
     default <T> AsyncWrap<T> asyncMixin(Class<T> mixinClass, Object mixedIn) {
-        return asyncMixin(mixinClass, mixedIn, ExecutionMode.EXECUTE);
+        // end::refguide[]
+
+        return asyncMixin(mixinClass, mixedIn, ExecutionModes.EXECUTE);
+
+        // tag::refguide[]
+        // ...
     }
+    // end::refguide[]
+
 
+    //
     // -- ITERACTION EVENT HANDLING
+    //
 
     /**
      * All {@link InteractionListener}s that have been registered using
      * {@link #addInteractionListener(InteractionListener)}.
      */
+    // tag::refguide[]
     List<InteractionListener> getListeners();
 
+    // end::refguide[]
     /**
      * Registers an {@link InteractionListener}, to be notified of interactions
      * on all wrappers.
@@ -269,8 +328,10 @@ public interface WrapperFactory {
      * @param listener
      * @return
      */
+    // tag::refguide[]
     boolean addInteractionListener(InteractionListener listener);
 
+    // end::refguide[]
     /**
      * Remove an {@link InteractionListener}, to no longer be notified of
      * interactions on wrappers.
@@ -284,6 +345,7 @@ public interface WrapperFactory {
      * @param listener
      * @return
      */
+    // tag::refguide[]
     boolean removeInteractionListener(InteractionListener listener);
 
     void notifyListeners(InteractionEvent ev);
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/WrappingObject.java b/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/WrappingObject.java
index 6e12f63..9c936cf 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/WrappingObject.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/WrappingObject.java
@@ -27,8 +27,10 @@ import org.apache.isis.core.commons.collections.ImmutableEnumSet;
  * Implemented by all objects that have been viewed as per
  * {@link org.apache.isis.applib.services.wrapper.WrapperFactory#wrap(Object)}.
  */
+// tag::refguide[]
 public interface WrappingObject {
 
+    // end::refguide[]
     /**
      * Programmatic equivalent of invoking save for a transient object .
      *
@@ -37,8 +39,10 @@ public interface WrappingObject {
      * intended to reduce the risk of a collision.
      * </p>
      */
+    // tag::refguide[]
     void __isis_save();
 
+    // end::refguide[]
     /**
      * Provide access to the underlying, wrapped object.
      *
@@ -56,17 +60,22 @@ public interface WrappingObject {
      * <b>NOTE: there is a string-literal reference to this name
      * <tt>DomainObjectInvocationHandler</tt>, so it should not be changed.</b>.
      */
+    // tag::refguide[]
     Object __isis_wrapped();
 
+    // end::refguide[]
     /**
      * The {@link EnumSet<WrapperFactory.ExecutionMode> execution mode}
      * with which this wrapper was
-     * {@link WrapperFactory#wrap(Object, EnumSet) created}.
+     * {@link WrapperFactory#wrap(Object, ImmutableEnumSet) created}.
      *
      * <p>
      * NOTE: domain classes may not have a method with this name.  The <tt>__isis_</tt> prefix is
      * intended to reduce the risk of a collision.
      * </p>
      */
+    // tag::refguide[]
     ImmutableEnumSet<WrapperFactory.ExecutionMode> __isis_executionMode();
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/events/InteractionEvent.java b/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/events/InteractionEvent.java
index 50d3f48..ea74096 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/events/InteractionEvent.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/wrapper/events/InteractionEvent.java
@@ -22,7 +22,7 @@ package org.apache.isis.applib.services.wrapper.events;
 import java.util.List;
 
 import org.apache.isis.applib.Identifier;
-import org.apache.isis.applib.events.domain.EventObjectBase;
+import org.apache.isis.applib.events.EventObjectBase;
 
 /**
  * <i>Supported only by {@link org.apache.isis.applib.services.wrapper.WrapperFactory} service, </i> 
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/xactn/Transaction.java b/api/applib/src/main/java/org/apache/isis/applib/services/xactn/Transaction.java
index 257a64d..7ba0a5f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/xactn/Transaction.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/xactn/Transaction.java
@@ -29,6 +29,7 @@ public interface Transaction {
 
     TransactionId getId();
 
+    // end::refguide[]
     /**
      * Flush all changes to the object store.
      *
@@ -41,6 +42,7 @@ public interface Transaction {
      *     Equivalent to {@link TransactionService#flushTransaction()}.
      * </p>
      */
+    // tag::refguide[]
     void flush();
 
     TransactionState getTransactionState();
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionId.java b/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionId.java
index 9353115..8536f13 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionId.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionId.java
@@ -24,22 +24,28 @@ import org.apache.isis.applib.services.HasUniqueId;
 
 import lombok.Data;
 
+// tag::refguide[]
 @Data(staticConstructor = "of")
 public final class TransactionId implements HasUniqueId {
 
     private final UUID uniqueId;
 
+    // end::refguide[]
     /**
-     * The {@link HasUniqueId#getUniqueId()} is (as of 1.13.0) actually an identifier for the request/
-     * interaction, and there can actually be multiple transactions within such a request/interaction.  
+     * The {@link HasUniqueId#getUniqueId()} is actually an identifier for the request/
+     * interaction, and there can actually be multiple transactions within such a request/interaction.
      * The sequence (0-based) is used to distinguish such.
      */
+    // tag::refguide[]
     private final int sequence;
 
-    private static final TransactionId EMPTY = TransactionId.of(UUID.fromString("0000-00-00-00-000000"), 0); 
+    // end::refguide[]
+    private static final TransactionId EMPTY = TransactionId.of(UUID.fromString("0000-00-00-00-000000"), 0);
 
     public static TransactionId empty() {
         return EMPTY;
     }
 
+    // tag::refguide[]
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionService.java b/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionService.java
index 4c1e19c..27264a9 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionService.java
@@ -27,13 +27,17 @@ import java.util.function.Supplier;
 // tag::refguide[]
 public interface TransactionService {
 
+    // end::refguide[]
     /**
-     * When called within an existing transactional boundary returns an unique id,
+     * When called within an existing transactional boundary returns the unique identifier to the transaction,
      * {@code null} otherwise.
+     *
      * @return nullable
      */
+    // tag::refguide[]
     TransactionId currentTransactionId();
 
+    // end::refguide[]
     /**
      * Flush all changes to the object store.
      *
@@ -41,43 +45,51 @@ public interface TransactionService {
      * Occasionally useful to ensure that newly persisted domain objects
      * are flushed to the database prior to a subsequent repository query.
      * </p>
-     *
-     * <p>
-     *     Equivalent to {@link Transaction#flush()} (with {@link Transaction} obtained using {@link #currentTransaction()}).
-     * </p>
      */
+    // tag::refguide[]
     void flushTransaction();
 
+    // end::refguide[]
     /**
-     * Generally this is equivalent to using {@link #currentTransaction()} and {@link Transaction#getTransactionState()}.
-     * However, if there is no current transaction, then this will return {@link TransactionState#NONE}.
+     * @return - the state of the current transaction.  If there is no current transaction, then returns {@link TransactionState#NONE}.
      */
+    // tag::refguide[]
     TransactionState currentTransactionState();
 
+    // end::refguide[]
     /**
      * Runs given {@code task} within an existing transactional boundary, or in the absence of such a
      * boundary creates a new one.
+     *
      * @param task
      */
+    // tag::refguide[]
     void executeWithinTransaction(Runnable task);
 
+    // end::refguide[]
     /**
      * Runs given {@code task} within an existing transactional boundary, or in the absence of such a
      * boundary creates a new one.
+     *
      * @param task
      */
+    // tag::refguide[]
     <T> T executeWithinTransaction(Supplier<T> task);
 
+    // end::refguide[]
     /**
      * Runs given {@code task} within its own (new) transactional boundary.
      * @param task
      */
+    // tag::refguide[]
     void executeWithinNewTransaction(Runnable task);
 
+    // end::refguide[]
     /**
      * Runs given {@code task} within its own (new) transactional boundary.
      * @param task
      */
+    // tag::refguide[]
     <T> T executeWithinNewTransaction(Supplier<T> task);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionState.java b/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionState.java
index 187ed7d..d1be4e4 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionState.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/xactn/TransactionState.java
@@ -18,19 +18,27 @@
  */
 package org.apache.isis.applib.services.xactn;
 
+// tag::refguide[]
 public enum TransactionState {
 
+    // end::refguide[]
     /**
      * No transaction exists.
      */
+    // tag::refguide[]
     NONE,
+
+    // end::refguide[]
     /**
      * Started, still in progress.
      * <p/>
      * <p/>
      * May flush, commit or abort.
      */
+    // tag::refguide[]
     IN_PROGRESS,
+
+    // end::refguide[]
     /**
      * Started, but has hit an exception.
      * <p/>
@@ -41,21 +49,31 @@ public enum TransactionState {
      * <p/>
      * Similar to <tt>setRollbackOnly</tt> in EJBs.
      */
+    // tag::refguide[]
     MUST_ABORT,
+
+    // end::refguide[]
     /**
      * Completed, having successfully committed.
      * <p/>
      * <p/>
      * May not flush or abort or commit (will throw {@link IllegalStateException}).
      */
+    // tag::refguide[]
     COMMITTED,
+
+    // end::refguide[]
     /**
      * Completed, having aborted.
      * <p/>
      * <p/>
      * May not flush, commit or abort (will throw {@link IllegalStateException}).
      */
-    ABORTED;
+    // tag::refguide[]
+    ABORTED
+
+    // end::refguide[]
+    ;
 
     private TransactionState() {
     }
@@ -91,4 +109,8 @@ public enum TransactionState {
     public boolean mustAbort() {
         return this == MUST_ABORT;
     }
+
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/services/xmlsnapshot/XmlSnapshotService.java b/api/applib/src/main/java/org/apache/isis/applib/services/xmlsnapshot/XmlSnapshotService.java
index 0621a0a..88e6bd9 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/services/xmlsnapshot/XmlSnapshotService.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/services/xmlsnapshot/XmlSnapshotService.java
@@ -35,8 +35,8 @@ import org.apache.isis.applib.annotation.Programmatic;
 // tag::refguide[]
 public interface XmlSnapshotService {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     interface Snapshot {
         Document getXmlDocument();
         Document getXsdDocument();
@@ -44,17 +44,17 @@ public interface XmlSnapshotService {
         String getXmlDocumentAsString();
         String getXsdDocumentAsString();
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide-2[]
+    // tag::refguide-2[]
     interface Builder {
         void includePath(final String path);
         void includePathAndAnnotation(final String path, final String annotation);
         XmlSnapshotService.Snapshot build();
     }
-// end::refguide-2[]
+    // end::refguide-2[]
 
-// tag::refguide-3[]
+    // tag::refguide-3[]
     class Exception extends RuntimeException {
 
         private static final long serialVersionUID = 1L;
@@ -75,32 +75,40 @@ public interface XmlSnapshotService {
             super(cause);
         }
     }
-// end::refguide-3[]
+    // end::refguide-3[]
 
-// tag::refguide[]
+    // tag::refguide[]
     XmlSnapshotService.Snapshot snapshotFor(final Object domainObject);
 
     XmlSnapshotService.Builder builderFor(final Object domainObject);
 
+    // end::refguide[]
     /**
      * Convenience to convert xml string (eg as obtained by {@link Snapshot#getXmlDocumentAsString()} or
      * {@link Snapshot#getXsdDocumentAsString()}) back into a {@link Document W3C Document}.
      */
+    // tag::refguide[]
     Document asDocument(String xmlStr);
 
+    // end::refguide[]
     /**
      * Convenience method to extract value of an XML element, based on its type.
      */
+    // tag::refguide[]
     <T> T getChildElementValue(final Element el, final String tagname, final Class<T> expectedCls);
 
+    // end::refguide[]
     /**
      * Convenience method to walk XML document.
      */
+    // tag::refguide[]
     Element getChildElement(final Element el, final String tagname);
 
+    // end::refguide[]
     /**
      * Convenience method to obtain value of child text node.
      */
+    // tag::refguide[]
     String getChildTextValue(final Element el);
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/snapshot/SnapshottableWithInclusions.java b/api/applib/src/main/java/org/apache/isis/applib/snapshot/SnapshottableWithInclusions.java
index 2a3802e..bb70ec9 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/snapshot/SnapshottableWithInclusions.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/snapshot/SnapshottableWithInclusions.java
@@ -28,10 +28,15 @@ import org.apache.isis.applib.services.xmlsnapshot.XmlSnapshotService;
  * snapshot is to be created using the {@link XmlSnapshotService}, indicating
  * paths to be {@link XmlSnapshotService.Snapshot#} automatically include additional paths within the snapshot.
  */
+// tag::refguide[]
 public interface SnapshottableWithInclusions {
 
+    // end::refguide[]
     /**
      * Paths to include in the snapshot.
      */
+    // tag::refguide[]
     List<String> snapshotInclusions();
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/spec/AbstractSpecification2.java b/api/applib/src/main/java/org/apache/isis/applib/spec/AbstractSpecification2.java
index 7bd193f..2036587 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/spec/AbstractSpecification2.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/spec/AbstractSpecification2.java
@@ -40,6 +40,8 @@ import org.apache.isis.core.commons.internal.base._Casts;
  * Implementation note: inspired by (borrowed code from) Hamcrest's
  * <tt>TypeSafeMatcher</tt>.
  */
+// tag::refguide[]
+// end::refguide[]
 public abstract class AbstractSpecification2<T> implements Specification2 {
 
     public enum TypeChecking {
diff --git a/api/applib/src/main/java/org/apache/isis/applib/spec/Specification.java b/api/applib/src/main/java/org/apache/isis/applib/spec/Specification.java
index d52c2c2..f08d788 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/spec/Specification.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/spec/Specification.java
@@ -23,11 +23,16 @@ package org.apache.isis.applib.spec;
  * An implementation of the <i>Specification</i> pattern, as described in Eric
  * Evans' <i>Domain Driven Design</i>, p224.
  */
+// tag::refguide[]
 public interface Specification {
 
+    // end::refguide[]
     /**
      * If <tt>null</tt> then satisfied, otherwise is reason why the
      * specification is not satisfied.
      */
-    public String satisfies(Object obj);
+    // tag::refguide[]
+    String satisfies(Object obj);
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/spec/Specification2.java b/api/applib/src/main/java/org/apache/isis/applib/spec/Specification2.java
index c4d8233..6b391b1 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/spec/Specification2.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/spec/Specification2.java
@@ -29,10 +29,15 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
  *     it will never be called by the framework.
  * </p>
  */
+// tag::refguide[]
 public interface Specification2 extends Specification {
 
+    // end::refguide[]
     /**
      * If <tt>null</tt> then satisfied, otherwise is the reason (as a {@link TranslatableString} translatable string) as to why the specification is not satisfied.
      */
-    public TranslatableString satisfiesTranslatable(Object obj);
+    // tag::refguide[]
+    TranslatableString satisfiesTranslatable(Object obj);
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationAnd.java b/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationAnd.java
index df97725..d66e00f 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationAnd.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationAnd.java
@@ -43,6 +43,7 @@ import org.apache.isis.applib.util.ReasonBuffer;
  * @see SpecificationOr
  * @see SpecificationNot
  */
+// tag::refguide[]
 public abstract class SpecificationAnd implements Specification {
 
     private final Specification[] specifications;
@@ -62,3 +63,4 @@ public abstract class SpecificationAnd implements Specification {
     }
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationNot.java b/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationNot.java
index a8af79f..64ffffa 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationNot.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationNot.java
@@ -44,6 +44,7 @@ package org.apache.isis.applib.spec;
  * @see SpecificationAnd
  * @see SpecificationOr
  */
+// tag::refguide[]
 public abstract class SpecificationNot implements Specification {
 
     private final Specification specification;
@@ -58,3 +59,4 @@ public abstract class SpecificationNot implements Specification {
         return satisfies != null ? null : "not satisfied";
     }
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationOr.java b/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationOr.java
index 1e14584..62029f5 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationOr.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/spec/SpecificationOr.java
@@ -43,6 +43,7 @@ import org.apache.isis.applib.util.ReasonBuffer;
  * @see SpecificationAnd
  * @see SpecificationNot
  */
+// tag::refguide[]
 public abstract class SpecificationOr implements Specification {
 
     private final Specification[] specifications;
@@ -62,7 +63,8 @@ public abstract class SpecificationOr implements Specification {
             }
             buf.append(reasonNotSatisfiedIfAny);
         }
-        return buf.getReason(); // may be null if all were satisfied.
+        return buf.getReason(); // will be non-null if none were satisfied.
     }
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/java/org/apache/isis/applib/types/DescriptionType.java b/api/applib/src/main/java/org/apache/isis/applib/types/DescriptionType.java
index 86f008f..048147b 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/types/DescriptionType.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/types/DescriptionType.java
@@ -18,16 +18,14 @@
  */
 package org.apache.isis.applib.types;
 
-public class DescriptionType {
+import lombok.experimental.UtilityClass;
 
-    private DescriptionType() {}
+@UtilityClass
+public class DescriptionType {
 
+    @UtilityClass
     public static class Meta {
-
         public static final int MAX_LEN = 254;
-
-        private Meta() {}
-
     }
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/types/MemberIdentifierType.java b/api/applib/src/main/java/org/apache/isis/applib/types/MemberIdentifierType.java
index 4e65cab..da151fc 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/types/MemberIdentifierType.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/types/MemberIdentifierType.java
@@ -24,6 +24,8 @@ import java.util.UUID;
 import org.apache.isis.applib.services.bookmark.Bookmark;
 import org.apache.isis.applib.services.command.Command;
 
+import lombok.experimental.UtilityClass;
+
 /**
  * As per {@link Command#getMemberIdentifier()} and {@link org.apache.isis.applib.services.audit.AuditerService#audit(UUID, int, String, Bookmark, String, String, String, String, String, Timestamp)}.
  */
@@ -32,12 +34,8 @@ public class MemberIdentifierType {
     private MemberIdentifierType() {
     }
 
+    @UtilityClass
     public static class Meta {
-
         public static final int MAX_LEN = 255;
-
-        private Meta() {
-        }
-
     }
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/types/TargetActionType.java b/api/applib/src/main/java/org/apache/isis/applib/types/TargetActionType.java
index 3da8d53..c9a6ce6 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/types/TargetActionType.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/types/TargetActionType.java
@@ -24,19 +24,17 @@ import java.util.UUID;
 import org.apache.isis.applib.services.bookmark.Bookmark;
 import org.apache.isis.applib.services.command.Command;
 
+import lombok.experimental.UtilityClass;
+
 /**
  * A user-friendly name of an action, as per {@link Command#getTargetAction()}, {@link org.apache.isis.applib.services.audit.AuditerService#audit(UUID, int, String, Bookmark, String, String, String, String, String, Timestamp)}.
  */
+@UtilityClass
 public class TargetActionType {
 
-    private TargetActionType() {}
-
+    @UtilityClass
     public static class Meta {
-
         public static final int MAX_LEN = 50;
-
-        private Meta() {}
-
     }
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/types/TargetClassType.java b/api/applib/src/main/java/org/apache/isis/applib/types/TargetClassType.java
index f0cccfe..b955bc8 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/types/TargetClassType.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/types/TargetClassType.java
@@ -24,19 +24,17 @@ import java.util.UUID;
 import org.apache.isis.applib.services.bookmark.Bookmark;
 import org.apache.isis.applib.services.command.Command;
 
+import lombok.experimental.UtilityClass;
+
 /**
  * A user-friendly name of a class, as per {@link Command#getTargetClass()}, {@link org.apache.isis.applib.services.audit.AuditerService#audit(UUID, int, String, Bookmark, String, String, String, String, String, Timestamp)}.
  */
+@UtilityClass
 public class TargetClassType {
 
-    private TargetClassType() {}
-
+    @UtilityClass
     public static class Meta {
-
         public static final int MAX_LEN = 50;
-
-        private Meta() {}
-
     }
 
 }
diff --git a/api/applib/src/main/java/org/apache/isis/applib/util/Enums.java b/api/applib/src/main/java/org/apache/isis/applib/util/Enums.java
index d2d3129..9f342ba 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/util/Enums.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/util/Enums.java
@@ -23,9 +23,10 @@ import java.util.stream.Collectors;
 
 import org.apache.isis.core.commons.internal.base._Strings;
 
-public final class Enums {
+import lombok.experimental.UtilityClass;
 
-    private Enums(){}
+@UtilityClass
+public final class Enums {
 
     public static String getFriendlyNameOf(Enum<?> anEnum) {
         return getFriendlyNameOf(anEnum.name());
diff --git a/api/applib/src/main/java/org/apache/isis/applib/util/JaxbUtil.java b/api/applib/src/main/java/org/apache/isis/applib/util/JaxbUtil.java
index ae8f8a1..f2919f0 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/util/JaxbUtil.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/util/JaxbUtil.java
@@ -35,6 +35,7 @@ import org.apache.isis.core.commons.internal.collections._Maps;
 import org.apache.isis.core.commons.internal.resources._Resources;
 
 import lombok.val;
+import lombok.experimental.UtilityClass;
 
 
 /**
@@ -46,10 +47,9 @@ import lombok.val;
  * (non-ASF)
  * </p>
  */
+@UtilityClass
 public class JaxbUtil {
 
-    private JaxbUtil(){}
-
     // -- READ
 
     public static <T> T fromXml(
diff --git a/api/applib/src/main/java/org/apache/isis/applib/value/Blob.java b/api/applib/src/main/java/org/apache/isis/applib/value/Blob.java
index 4a6956c..028aa33 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/value/Blob.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/value/Blob.java
@@ -30,6 +30,8 @@ import org.apache.isis.core.commons.internal.base._Strings;
 
 import lombok.val;
 
+// tag::refguide[]
+// end::refguide[]
 public final class Blob implements NamedWithMimeType {
 
     /**
diff --git a/api/applib/src/main/java/org/apache/isis/applib/value/Clob.java b/api/applib/src/main/java/org/apache/isis/applib/value/Clob.java
index f7311a4..e1baa9d 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/value/Clob.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/value/Clob.java
@@ -29,6 +29,8 @@ import org.apache.isis.core.commons.internal.base._Strings;
 
 import lombok.val;
 
+// tag::refguide[]
+// end::refguide[]
 public final class Clob implements NamedWithMimeType {
 
     private static final long serialVersionUID = 8694189924062378527L;
diff --git a/api/applib/src/main/java/org/apache/isis/applib/value/Image.java b/api/applib/src/main/java/org/apache/isis/applib/value/Image.java
index e282895..63df43c 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/value/Image.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/value/Image.java
@@ -26,6 +26,8 @@ import org.apache.isis.applib.annotation.Value;
 /**
  * Represents an image.
  */
+// tag::refguide[]
+// end::refguide[]
 @Value(semanticsProviderName = "org.apache.isis.core.metamodel.facets.value.image.ImageValueSemanticsProvider")
 public class Image implements Serializable {
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/java/org/apache/isis/applib/value/LocalResourcePath.java b/api/applib/src/main/java/org/apache/isis/applib/value/LocalResourcePath.java
index 915bc2b..a0eb7c6 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/value/LocalResourcePath.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/value/LocalResourcePath.java
@@ -31,6 +31,8 @@ import lombok.NonNull;
 /**
  * Represents a local resource path, typically a relative path originating at this web-app's root or context-root.
  */
+// tag::refguide[]
+// end::refguide[]
 @Value(semanticsProviderName = "org.apache.isis.core.metamodel.facets.value.localrespath.LocalResourcePathValueSemanticsProvider")
 public final class LocalResourcePath implements Serializable {
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/java/org/apache/isis/applib/value/Markup.java b/api/applib/src/main/java/org/apache/isis/applib/value/Markup.java
index c70d337..9b45652 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/value/Markup.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/value/Markup.java
@@ -27,6 +27,8 @@ import org.apache.isis.applib.annotation.Value;
  * Immutable value type holding pre-rendered HTML.
  *
  */
+// tag::refguide[]
+// end::refguide[]
 @Value(semanticsProviderName = "org.apache.isis.core.metamodel.facets.value.markup.MarkupValueSemanticsProvider")
 public class Markup implements Serializable {
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/java/org/apache/isis/applib/value/NamedWithMimeType.java b/api/applib/src/main/java/org/apache/isis/applib/value/NamedWithMimeType.java
index 796dc7e..19e01a7 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/value/NamedWithMimeType.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/value/NamedWithMimeType.java
@@ -28,6 +28,8 @@ import org.apache.isis.core.commons.collections.Can;
 
 import lombok.Getter;
 
+// tag::refguide[]
+// end::refguide[]
 public interface NamedWithMimeType extends Serializable {
 
     public String getName();
diff --git a/api/applib/src/main/java/org/apache/isis/applib/value/Password.java b/api/applib/src/main/java/org/apache/isis/applib/value/Password.java
index 01a8435..fe536dd 100644
--- a/api/applib/src/main/java/org/apache/isis/applib/value/Password.java
+++ b/api/applib/src/main/java/org/apache/isis/applib/value/Password.java
@@ -24,6 +24,8 @@ import java.util.Objects;
 
 import org.apache.isis.applib.annotation.Value;
 
+// tag::refguide[]
+// end::refguide[]
 @Value(semanticsProviderName = "org.apache.isis.core.metamodel.facets.value.password.PasswordValueSemanticsProvider")
 @lombok.Value
 public class Password implements Serializable {
diff --git a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/DomainEventHelper.java b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/DomainEventHelper.java
index eba843c..ac6056f 100644
--- a/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/DomainEventHelper.java
+++ b/core/metamodel/src/main/java/org/apache/isis/core/metamodel/facets/DomainEventHelper.java
@@ -130,7 +130,7 @@ public class DomainEventHelper {
 
                 if(objectAction != null) {
                     // should always be the case...
-                    event.setActionSemantics(objectAction.getSemantics());
+                    event.setSemantics(objectAction.getSemantics());
 
                     val parameters = objectAction.getParameters();
 
diff --git a/core/runtime/src/main/java/org/apache/isis/core/runtime/persistence/transaction/ChangedObjectsService.java b/core/runtime/src/main/java/org/apache/isis/core/runtime/persistence/transaction/ChangedObjectsService.java
index 8535c05..63d2177 100644
--- a/core/runtime/src/main/java/org/apache/isis/core/runtime/persistence/transaction/ChangedObjectsService.java
+++ b/core/runtime/src/main/java/org/apache/isis/core/runtime/persistence/transaction/ChangedObjectsService.java
@@ -54,9 +54,10 @@ import lombok.extern.log4j.Log4j2;
 @Qualifier("Default")
 @RequestScoped
 @Log4j2
+// tag::refguide[]
 public class ChangedObjectsService implements WithTransactionScope {
 
-// end::refguide[]
+    // end::refguide[]
     public ChangedObjectsService() {
         log.debug("init");
     }
@@ -71,7 +72,6 @@ public class ChangedObjectsService implements WithTransactionScope {
         log.debug("preDestroy");
     }
 
-// tag::refguide[]
     /**
      * Used for auditing: this contains the pre- values of every property of every object enlisted.
      *
@@ -80,6 +80,7 @@ public class ChangedObjectsService implements WithTransactionScope {
      *     the actual differences.
      * </p>
      */
+    // tag::refguide[]
     private final Map<AdapterAndProperty, PreAndPostValues> enlistedObjectProperties = _Maps.newLinkedHashMap();
 
     /**
diff --git a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/userreg/EmailNotificationServiceDefault.java b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/userreg/EmailNotificationServiceDefault.java
index fb57286..0b2144c 100644
--- a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/userreg/EmailNotificationServiceDefault.java
+++ b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/userreg/EmailNotificationServiceDefault.java
@@ -75,7 +75,6 @@ public class EmailNotificationServiceDefault implements EmailNotificationService
     /**
      * Loads responsive email templates borrowed from http://zurb.com/ink/templates.php (Basic)
      */
-    @Override
     @PostConstruct
     public void init() {
 
diff --git a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/wrapper/AsyncWrapDefault.java b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/wrapper/AsyncWrapDefault.java
index d8f986f..a76ee78 100644
--- a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/wrapper/AsyncWrapDefault.java
+++ b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/wrapper/AsyncWrapDefault.java
@@ -94,14 +94,14 @@ class AsyncWrapDefault<T> implements AsyncWrap<T> {
         
         if(shouldValidate()) {
             // do validation synchronous (with the calling thread)
-            val proxy_validateOnly = wrapper.wrap(domainObject, ExecutionMode.NO_EXECUTE);
+            val proxy_validateOnly = wrapper.wrap(domainObject, WrapperFactory.ExecutionModes.NO_EXECUTE);
             action.call(proxy_validateOnly);
         }
         
         if(shouldExecute()) {
             // to also trigger domain events, we need a proxy, but validation (if required)
             // was already done above
-            val proxy_executeOnly = wrapper.wrap(domainObject, ExecutionMode.SKIP_RULES);
+            val proxy_executeOnly = wrapper.wrap(domainObject, WrapperFactory.ExecutionModes.SKIP_RULES);
             return submit(()->action.call(proxy_executeOnly));
         }
         
@@ -114,14 +114,14 @@ class AsyncWrapDefault<T> implements AsyncWrap<T> {
         
         if(shouldValidate()) {
             // do validation synchronous (with the calling thread)
-            val proxy_validateOnly = wrapper.wrap(domainObject, ExecutionMode.NO_EXECUTE);
+            val proxy_validateOnly = wrapper.wrap(domainObject, WrapperFactory.ExecutionModes.NO_EXECUTE);
             action.call(proxy_validateOnly, arg1);
         }
         
         if(shouldExecute()) {
             // to also trigger domain events, we need a proxy, but validation (if required)
             // was already done above
-            val proxy_executeOnly = wrapper.wrap(domainObject, ExecutionMode.SKIP_RULES);
+            val proxy_executeOnly = wrapper.wrap(domainObject, WrapperFactory.ExecutionModes.SKIP_RULES);
             return submit(()->action.call(proxy_executeOnly, arg1));
         }
         
@@ -133,14 +133,14 @@ class AsyncWrapDefault<T> implements AsyncWrap<T> {
 
         if(shouldValidate()) {
             // do validation synchronous (with the calling thread)
-            val proxy_validateOnly = wrapper.wrap(domainObject, ExecutionMode.NO_EXECUTE);
+            val proxy_validateOnly = wrapper.wrap(domainObject, WrapperFactory.ExecutionModes.NO_EXECUTE);
             action.call(proxy_validateOnly, arg1, arg2);
         }
         
         if(shouldExecute()) {
             // to also trigger domain events, we need a proxy, but validation (if required)
             // was already done above
-            val proxy_executeOnly = wrapper.wrap(domainObject, ExecutionMode.SKIP_RULES);
+            val proxy_executeOnly = wrapper.wrap(domainObject, WrapperFactory.ExecutionModes.SKIP_RULES);
             return submit(()->action.call(proxy_executeOnly, arg1, arg2));
         }
         
@@ -154,14 +154,14 @@ class AsyncWrapDefault<T> implements AsyncWrap<T> {
         
         if(shouldValidate()) {
             // do validation synchronous (with the calling thread)
-            val proxy_validateOnly = wrapper.wrap(domainObject, ExecutionMode.NO_EXECUTE);
+            val proxy_validateOnly = wrapper.wrap(domainObject, WrapperFactory.ExecutionModes.NO_EXECUTE);
             action.call(proxy_validateOnly, arg1, arg2, arg3);
         }
         
         if(shouldExecute()) {
          // to also trigger domain events, we need a proxy, but validation (if required)
             // was already done above
-            val proxy_executeOnly = wrapper.wrap(domainObject, ExecutionMode.SKIP_RULES);
+            val proxy_executeOnly = wrapper.wrap(domainObject, WrapperFactory.ExecutionModes.SKIP_RULES);
             return submit(()->action.call(proxy_executeOnly, arg1, arg2, arg3));
         }
         
@@ -175,14 +175,14 @@ class AsyncWrapDefault<T> implements AsyncWrap<T> {
 
         if(shouldValidate()) {
             // do validation synchronous (with the calling thread)
-            val proxy_validateOnly = wrapper.wrap(domainObject, ExecutionMode.NO_EXECUTE);
+            val proxy_validateOnly = wrapper.wrap(domainObject, WrapperFactory.ExecutionModes.NO_EXECUTE);
             action.call(proxy_validateOnly, arg1, arg2, arg3, arg4);
         }
         
         if(shouldExecute()) {
             // to also trigger domain events, we need a proxy, but validation (if required)
             // was already done above
-            val proxy_executeOnly = wrapper.wrap(domainObject, ExecutionMode.SKIP_RULES);
+            val proxy_executeOnly = wrapper.wrap(domainObject, WrapperFactory.ExecutionModes.SKIP_RULES);
             return submit(()->action.call(proxy_executeOnly, arg1, arg2, arg3, arg4));
         }
         
diff --git a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/wrapper/WrapperFactoryDefault.java b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/wrapper/WrapperFactoryDefault.java
index 182b7b4..2949494 100644
--- a/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/wrapper/WrapperFactoryDefault.java
+++ b/core/runtimeservices/src/main/java/org/apache/isis/core/runtimeservices/wrapper/WrapperFactoryDefault.java
@@ -133,22 +133,22 @@ public class WrapperFactoryDefault implements WrapperFactory {
 
     @Override
     public <T> T wrap(T domainObject) {
-        return wrap(domainObject, ExecutionMode.EXECUTE);
+        return wrap(domainObject, ExecutionModes.EXECUTE);
     }
 
     @Override
     public <T> T wrapTry(T domainObject) {
-        return wrap(domainObject, ExecutionMode.TRY);
+        return wrap(domainObject, ExecutionModes.TRY);
     }
 
     @Override
     public <T> T wrapNoExecute(T domainObject) {
-        return wrap(domainObject, ExecutionMode.NO_EXECUTE);
+        return wrap(domainObject, ExecutionModes.NO_EXECUTE);
     }
 
     @Override
     public <T> T wrapSkipRules(T domainObject) {
-        return wrap(domainObject, ExecutionMode.SKIP_RULES);
+        return wrap(domainObject, ExecutionModes.SKIP_RULES);
     }
 
     @Override
diff --git a/core/runtimeservices/src/test/java/org/apache/isis/core/metamodel/commons/internal/reflection/ReflectTest.java b/core/runtimeservices/src/test/java/org/apache/isis/core/metamodel/commons/internal/reflection/ReflectTest.java
index 164f7d2..4c13e64 100644
--- a/core/runtimeservices/src/test/java/org/apache/isis/core/metamodel/commons/internal/reflection/ReflectTest.java
+++ b/core/runtimeservices/src/test/java/org/apache/isis/core/metamodel/commons/internal/reflection/ReflectTest.java
@@ -31,6 +31,7 @@ import static org.junit.jupiter.api.Assertions.assertNotNull;
 
 import org.apache.isis.applib.annotation.Programmatic;
 import org.apache.isis.applib.services.jaxb.JaxbServiceDefault;
+import org.apache.isis.core.commons.collections.Can;
 import org.apache.isis.core.commons.internal.collections._Sets;
 import org.apache.isis.core.commons.internal.reflection._Reflect.InterfacePolicy;
 import org.apache.isis.core.runtimeservices.user.UserServiceDefault;
@@ -98,11 +99,15 @@ class ReflectTest {
 
     }
 
+    @Programmatic
+    public void annotationLookupTestMethod(final String username, final List<String> roles) {
+    }
+
     @Test
     void annotationLookup() throws NoSuchMethodException, SecurityException {
 
-        Class<?> type = UserServiceDefault.SudoServiceSpi.class;
-        Method method = type.getMethod("runAs", new Class[] {String.class, List.class});
+        Class<?> type = getClass();
+        Method method = type.getMethod("annotationLookupTestMethod", new Class[] {String.class, List.class});
 
         Programmatic annot = getAnnotation(method, Programmatic.class, true, true);
 
diff --git a/core/runtimeservices/src/test/java/org/apache/isis/core/runtimeservices/wrapper/WrapperFactoryDefaultTest.java b/core/runtimeservices/src/test/java/org/apache/isis/core/runtimeservices/wrapper/WrapperFactoryDefaultTest.java
index b1d36ff..6b54786 100644
--- a/core/runtimeservices/src/test/java/org/apache/isis/core/runtimeservices/wrapper/WrapperFactoryDefaultTest.java
+++ b/core/runtimeservices/src/test/java/org/apache/isis/core/runtimeservices/wrapper/WrapperFactoryDefaultTest.java
@@ -98,7 +98,7 @@ public class WrapperFactoryDefaultTest {
         wrapperFactory.wrap(domainObject);
 
         assertThat(createProxyCalledWithDomainObject, is(domainObject));
-        assertThat(createProxyCalledWithMode, is(WrapperFactory.ExecutionMode.EXECUTE));
+        assertThat(createProxyCalledWithMode, is(WrapperFactory.ExecutionModes.EXECUTE));
     }
 
 
@@ -106,10 +106,10 @@ public class WrapperFactoryDefaultTest {
     public void wrap_ofWrapped_sameMode_returnsUnchanged() throws Exception {
         // given
         final DomainObject wrappedObject = new DomainObject();
-        final DomainObject domainObject = new WrappedDomainObject(wrappedObject, WrapperFactory.ExecutionMode.EXECUTE);
+        final DomainObject domainObject = new WrappedDomainObject(wrappedObject, WrapperFactory.ExecutionModes.EXECUTE);
 
         // when
-        final DomainObject wrappingObject = wrapperFactory.wrap(domainObject, WrapperFactory.ExecutionMode.EXECUTE);
+        final DomainObject wrappingObject = wrapperFactory.wrap(domainObject, WrapperFactory.ExecutionModes.EXECUTE);
 
         // then
         assertThat(wrappingObject, is(domainObject));
@@ -120,15 +120,15 @@ public class WrapperFactoryDefaultTest {
     public void wrap_ofWrapped_differentMode_delegates_to_createProxy() throws Exception {
         // given
         final DomainObject wrappedObject = new DomainObject();
-        final DomainObject domainObject = new WrappedDomainObject(wrappedObject, WrapperFactory.ExecutionMode.EXECUTE);
+        final DomainObject domainObject = new WrappedDomainObject(wrappedObject, WrapperFactory.ExecutionModes.EXECUTE);
 
         // when
-        final DomainObject wrappingObject = wrapperFactory.wrap(domainObject, WrapperFactory.ExecutionMode.SKIP_RULES);
+        final DomainObject wrappingObject = wrapperFactory.wrap(domainObject, WrapperFactory.ExecutionModes.SKIP_RULES);
 
         // then
         assertThat(wrappingObject, is(not(domainObject)));
         assertThat(createProxyCalledWithDomainObject, is(wrappedObject));
-        assertThat(createProxyCalledWithMode, is(WrapperFactory.ExecutionMode.SKIP_RULES));
+        assertThat(createProxyCalledWithMode, is(WrapperFactory.ExecutionModes.SKIP_RULES));
     }
 
 }
\ No newline at end of file
diff --git a/examples/smoketests/src/test/java/org/apache/isis/testdomain/auditing/AuditerServiceTest.java b/examples/smoketests/src/test/java/org/apache/isis/testdomain/auditing/AuditerServiceTest.java
index b0e9ed0..90b6a76 100644
--- a/examples/smoketests/src/test/java/org/apache/isis/testdomain/auditing/AuditerServiceTest.java
+++ b/examples/smoketests/src/test/java/org/apache/isis/testdomain/auditing/AuditerServiceTest.java
@@ -41,7 +41,6 @@ import static org.junit.jupiter.api.Assertions.assertThrows;
 import org.apache.isis.applib.services.repository.RepositoryService;
 import org.apache.isis.applib.services.wrapper.DisabledException;
 import org.apache.isis.applib.services.wrapper.WrapperFactory;
-import org.apache.isis.applib.services.wrapper.WrapperFactory.ExecutionMode;
 import org.apache.isis.core.config.presets.IsisPresets;
 import org.apache.isis.testdomain.Incubating;
 import org.apache.isis.testdomain.Smoketest;
@@ -131,7 +130,7 @@ class AuditerServiceTest {
         kvStore.clear(AuditerServiceForTesting.class);
 
         // when - running within its own background task
-        val future = wrapper.async(book, ExecutionMode.SKIP_RULES) // don't enforce rules for this test
+        val future = wrapper.async(book, WrapperFactory.ExecutionModes.SKIP_RULES) // don't enforce rules for this test
         .run(JdoBook::setName, "Book #2");
 
         future.get(1000, TimeUnit.SECONDS);
@@ -154,7 +153,7 @@ class AuditerServiceTest {
         // when - running within its own background task
         assertThrows(DisabledException.class, ()->{
         
-            val future = wrapper.async(book, ExecutionMode.EXECUTE)
+            val future = wrapper.async(book, WrapperFactory.ExecutionModes.EXECUTE)
                     .run(JdoBook::setName, "Book #2");
 
             future.get(1000, TimeUnit.SECONDS);
diff --git a/examples/smoketests/src/test/java/org/apache/isis/testdomain/publishing/PublisherServiceTest.java b/examples/smoketests/src/test/java/org/apache/isis/testdomain/publishing/PublisherServiceTest.java
index 51af7be..9f05b5a 100644
--- a/examples/smoketests/src/test/java/org/apache/isis/testdomain/publishing/PublisherServiceTest.java
+++ b/examples/smoketests/src/test/java/org/apache/isis/testdomain/publishing/PublisherServiceTest.java
@@ -43,7 +43,6 @@ import static org.junit.jupiter.api.Assertions.assertThrows;
 import org.apache.isis.applib.services.repository.RepositoryService;
 import org.apache.isis.applib.services.wrapper.DisabledException;
 import org.apache.isis.applib.services.wrapper.WrapperFactory;
-import org.apache.isis.applib.services.wrapper.WrapperFactory.ExecutionMode;
 import org.apache.isis.core.config.presets.IsisPresets;
 import org.apache.isis.core.metamodel.services.publishing.PublisherDispatchService;
 import org.apache.isis.testdomain.Incubating;
@@ -144,7 +143,7 @@ class PublisherServiceTest {
         val latch = kvStore.latch(PublisherServiceForTesting.class);
 
         // when - running within its own background task
-        val future = wrapper.async(book, ExecutionMode.SKIP_RULES) // don't enforce rules for this test
+        val future = wrapper.async(book, WrapperFactory.ExecutionModes.SKIP_RULES) // don't enforce rules for this test
                 .run(JdoBook::setName, "Book #2");
 
         future.get(10, TimeUnit.SECONDS);
@@ -174,7 +173,7 @@ class PublisherServiceTest {
         // when - running within its own background task
         assertThrows(DisabledException.class, ()->{
             
-            val future = wrapper.async(book, ExecutionMode.EXECUTE) 
+            val future = wrapper.async(book, WrapperFactory.ExecutionModes.EXECUTE)
                 .run(JdoBook::setName, "Book #2");
             
             future.get(10, TimeUnit.SECONDS);
diff --git a/testing/fixtures/applib/src/main/java/org/apache/isis/testing/fixtures/applib/events/FixturesInstalledEvent.java b/testing/fixtures/applib/src/main/java/org/apache/isis/testing/fixtures/applib/events/FixturesInstalledEvent.java
index 1de48d0..56c05f3 100644
--- a/testing/fixtures/applib/src/main/java/org/apache/isis/testing/fixtures/applib/events/FixturesInstalledEvent.java
+++ b/testing/fixtures/applib/src/main/java/org/apache/isis/testing/fixtures/applib/events/FixturesInstalledEvent.java
@@ -19,7 +19,7 @@
 
 package org.apache.isis.testing.fixtures.applib.events;
 
-import org.apache.isis.applib.events.domain.EventObjectBase;
+import org.apache.isis.applib.events.EventObjectBase;
 
 public class FixturesInstalledEvent extends EventObjectBase<Object> {
 
diff --git a/testing/fixtures/applib/src/main/java/org/apache/isis/testing/fixtures/applib/events/FixturesInstallingEvent.java b/testing/fixtures/applib/src/main/java/org/apache/isis/testing/fixtures/applib/events/FixturesInstallingEvent.java
index f34dab3..463f373 100644
--- a/testing/fixtures/applib/src/main/java/org/apache/isis/testing/fixtures/applib/events/FixturesInstallingEvent.java
+++ b/testing/fixtures/applib/src/main/java/org/apache/isis/testing/fixtures/applib/events/FixturesInstallingEvent.java
@@ -19,7 +19,7 @@
 
 package org.apache.isis.testing.fixtures.applib.events;
 
-import org.apache.isis.applib.events.domain.EventObjectBase;
+import org.apache.isis.applib.events.EventObjectBase;
 
 public class FixturesInstallingEvent extends EventObjectBase<Object> {
 


[isis] 02/02: ISIS-2062: updates examples

Posted by da...@apache.org.
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 33cd6802fd77ad520b3c484783db93187b38b8e8
Author: danhaywood <da...@haywood-associates.co.uk>
AuthorDate: Tue Mar 3 12:33:35 2020 +0000

    ISIS-2062: updates examples
---
 .../applib-ant/examples/annotation/Action.java     |  61 ++++---
 .../examples/annotation/ActionLayout.java          |  51 +++---
 .../applib-ant/examples/annotation/Auditing.java   |  15 ++
 .../examples/annotation/BookmarkPolicy.java        |  17 +-
 .../applib-ant/examples/annotation/Bounding.java   |   2 +
 .../applib-ant/examples/annotation/Collection.java |  39 +++--
 .../examples/annotation/CollectionLayout.java      |  44 ++---
 .../examples/annotation/CommandExecuteIn.java      |  22 +--
 .../examples/annotation/CommandPersistence.java    |  16 +-
 .../examples/annotation/CommandReification.java    |  15 ++
 .../applib-ant/examples/annotation/Constants.java  |  27 ---
 .../examples/annotation/Contributed.java           |  20 ++-
 .../applib-ant/examples/annotation/Defaulted.java  |   6 +
 .../examples/annotation/DomainObject.java          |  82 +++++----
 .../examples/annotation/DomainObjectLayout.java    |  56 ++++---
 .../examples/annotation/DomainService.java         |  23 ++-
 .../examples/annotation/DomainServiceLayout.java   |  17 +-
 .../applib-ant/examples/annotation/Editing.java    |  14 ++
 .../examples/annotation/EqualByContent.java        |   7 +-
 .../applib-ant/examples/annotation/Facets.java     |   7 +
 .../applib-ant/examples/annotation/HomePage.java   |   2 +
 .../examples/annotation/LabelPosition.java         |   9 +-
 .../examples/annotation/MemberOrder.java           |   6 +
 .../examples/annotation/MementoSerialization.java  |  12 ++
 .../applib-ant/examples/annotation/MinLength.java  |   3 +-
 .../applib-ant/examples/annotation/Mixin.java      |   6 +
 .../applib-ant/examples/annotation/Module.java     |   5 +-
 .../applib-ant/examples/annotation/Nature.java     |  29 +++-
 .../examples/annotation/NatureOfService.java       |  31 ++--
 .../applib-ant/examples/annotation/Navigable.java  |   9 +-
 .../examples/annotation/Optionality.java           |  27 ++-
 .../examples/annotation/OrderPrecedence.java       |  13 ++
 .../applib-ant/examples/annotation/Parameter.java  |  32 ++--
 .../examples/annotation/ParameterLayout.java       |  24 ++-
 .../examples/annotation/Programmatic.java          |  13 +-
 .../applib-ant/examples/annotation/Projecting.java |   8 +
 .../examples/annotation/PromptStyle.java           |  27 ++-
 .../applib-ant/examples/annotation/Property.java   |  92 +++++-----
 .../examples/annotation/PropertyLayout.java        |  26 ++-
 .../applib-ant/examples/annotation/Publishing.java |  15 ++
 .../examples/annotation/PublishingChangeKind.java  |   8 +-
 .../applib-ant/examples/annotation/Redirect.java   |  10 ++
 .../applib-ant/examples/annotation/RenderDay.java  |  12 +-
 .../applib-ant/examples/annotation/Repainting.java |  10 ++
 .../applib-ant/examples/annotation/RestrictTo.java |   6 +
 .../examples/annotation/SemanticsOf.java           |  35 +++-
 .../applib-ant/examples/annotation/Title.java      |  16 +-
 .../applib-ant/examples/annotation/Value.java      |   6 +
 .../applib-ant/examples/annotation/ViewModel.java  |  14 +-
 .../examples/annotation/ViewModelLayout.java       |  55 +++---
 .../applib-ant/examples/annotation/Where.java      |  65 ++++++++
 .../events/{domain => }/EventObjectBase.java       |  20 ++-
 .../events/domain/AbstractDomainEvent.java         | 185 +++++++++++++--------
 .../examples/events/domain/ActionDomainEvent.java  | 152 +++++++----------
 .../events/domain/CollectionDomainEvent.java       |  62 +++----
 .../events/domain/PropertyDomainEvent.java         |  55 +++---
 .../events/lifecycle/AbstractLifecycleEvent.java   |   6 +-
 .../events/lifecycle/ObjectCreatedEvent.java       |  23 +--
 .../events/lifecycle/ObjectLoadedEvent.java        |  25 +--
 .../events/lifecycle/ObjectPersistedEvent.java     |  24 +--
 .../events/lifecycle/ObjectPersistingEvent.java    |  22 +--
 .../events/lifecycle/ObjectRemovingEvent.java      |  22 +--
 .../events/lifecycle/ObjectUpdatedEvent.java       |  22 +--
 .../events/lifecycle/ObjectUpdatingEvent.java      |  22 +--
 .../examples/events/ui/AbstractUiEvent.java        |  11 +-
 .../examples/events/ui/CssClassUiEvent.java        |  56 ++++---
 .../examples/events/ui/LayoutUiEvent.java          |  64 ++++---
 .../applib-cm/examples/events/ui/TitleUiEvent.java |  45 ++---
 .../modules/applib-cm/examples/graph/Edge.java     |   7 +-
 .../applib-cm/examples/graph/SimpleEdge.java       |   2 +
 .../modules/applib-cm/examples/graph/Vertex.java   |  15 +-
 .../applib-cm/examples/security/RoleMemento.java   |  27 ++-
 .../applib-cm/examples/security/UserMemento.java   |  73 ++++----
 .../examples/spec/AbstractSpecification2.java      |   2 +
 .../applib-cm/examples/spec/Specification.java     |   7 +-
 .../applib-cm/examples/spec/Specification2.java    |   7 +-
 .../applib-cm/examples/spec/SpecificationAnd.java  |   2 +
 .../applib-cm/examples/spec/SpecificationNot.java  |   2 +
 .../applib-cm/examples/spec/SpecificationOr.java   |   4 +-
 .../modules/applib-cm/examples/util/Enums.java     |   5 +-
 .../modules/applib-cm/examples/util/JaxbUtil.java  |   4 +-
 .../modules/applib-cm/examples/value/Blob.java     |   2 +
 .../modules/applib-cm/examples/value/Clob.java     |   2 +
 .../modules/applib-cm/examples/value/Image.java    |   2 +
 .../examples/value/LocalResourcePath.java          |   2 +
 .../modules/applib-cm/examples/value/Markup.java   |   2 +
 .../examples/value/NamedWithMimeType.java          |   2 +
 .../modules/applib-cm/examples/value/Password.java |   2 +
 .../applib-svc/examples/services/HasUniqueId.java  |   4 +
 .../applib-svc/examples/services/HasUsername.java  |   4 +-
 .../examples/services/WithTransactionScope.java    |   2 +
 .../examples/services/metrics/MetricsService.java  |   4 +
 .../services/publish/PublishedObjects.java         |   3 -
 .../services/publish/PublisherService.java         |   2 +
 .../queryresultscache/QueryResultsCache.java       |  14 +-
 .../services/registry/ServiceRegistry.java         |  40 ++++-
 .../examples/services/repository/EntityState.java  |   8 +-
 .../services/repository/RepositoryService.java     |  35 +++-
 .../examples/services/routing/RoutingService.java  |   1 -
 .../examples/services/scratchpad/Scratchpad.java   |  12 +-
 .../services/session/SessionLoggingService.java    |  11 +-
 .../examples/services/sudo/SudoService.java        |  40 +++--
 .../examples/services/swagger/SwaggerService.java  |  26 ++-
 .../services/tablecol/TableColumnOrderService.java |   3 -
 .../examples/services/title/TitleService.java      |   4 +
 .../services/urlencoding/UrlEncodingService.java   |   1 +
 .../examples/services/user/UserService.java        |   2 +
 .../services/userprof/UserProfileService.java      |   2 +
 .../services/userreg/EmailNotificationService.java |   8 +-
 .../examples/services/userreg/UserDetails.java     |   3 +-
 .../examples/services/wrapper/WrapperFactory.java  | 106 +++++++++---
 .../examples/services/wrapper/WrappingObject.java  |  11 +-
 .../services/wrapper/events/InteractionEvent.java  |   2 +-
 .../examples/services/xactn/Transaction.java       |   2 +
 .../examples/services/xactn/TransactionId.java     |  12 +-
 .../services/xactn/TransactionService.java         |  26 ++-
 .../examples/services/xactn/TransactionState.java  |  24 ++-
 .../services/xmlsnapshot/XmlSnapshotService.java   |  24 ++-
 118 files changed, 1688 insertions(+), 902 deletions(-)

diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Action.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Action.java
index b9347b8..4549519 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Action.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Action.java
@@ -37,13 +37,18 @@ import org.apache.isis.applib.value.Clob;
 /**
  * Domain semantics for domain object collection.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.METHOD,
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE }
+)
 @Retention(RetentionPolicy.RUNTIME)
 @Mixin(method = "act")
 public @interface Action {
 
-
+    // end::refguide[]
     /**
      * Indicates that an invocation of the action should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -66,11 +71,10 @@ public @interface Action {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ActionDomainEvent<?>> domainEvent() default ActionDomainEvent.Default.class;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates where (in the UI) the action is not visible to the user.
      *
@@ -84,30 +88,34 @@ public @interface Action {
      *     {@link ActionLayout#contributed()}.
      * </p>
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The action semantics, either {@link SemanticsOf#SAFE_AND_REQUEST_CACHEABLE cached}, {@link SemanticsOf#SAFE safe} (query-only),
      * {@link SemanticsOf#IDEMPOTENT idempotent} or
      * {@link SemanticsOf#NON_IDEMPOTENT non-idempotent}.
      */
+    // tag::refguide[]
     SemanticsOf semantics() default SemanticsOf.NOT_SPECIFIED;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Whether the action invocation should be reified into a {@link org.apache.isis.applib.services.command.Command} object.
      */
+    // tag::refguide[]
     CommandReification command() default CommandReification.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * How the {@link org.apache.isis.applib.services.command.Command Command} object provided by the
      * {@link org.apache.isis.applib.services.command.CommandContext CommandContext} domain service should be persisted.
      */
+    // tag::refguide[]
     CommandPersistence commandPersistence() default CommandPersistence.PERSISTED;
 
+    // end::refguide[]
     /**
      * How the command/action should be executed.
      *
@@ -117,8 +125,10 @@ public @interface Action {
      * will be set to this value.
      * </p>
      */
+    // tag::refguide[]
     CommandExecuteIn commandExecuteIn() default CommandExecuteIn.FOREGROUND;
 
+    // end::refguide[]
     /**
      * The {@link CommandDtoProcessor} to process this command's DTO.
      *
@@ -133,12 +143,10 @@ public @interface Action {
      *     {@link ContentMappingServiceForCommandsDto} to dynamically transform the DTOs.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CommandDtoProcessor> commandDtoProcessor() default CommandDtoProcessor.class;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Whether the action invocation should be published.
      *
@@ -147,22 +155,18 @@ public @interface Action {
      * or {@link org.apache.isis.applib.services.publish.PublisherService} is registered with the framework.
      * </p>
      */
+    // tag::refguide[]
     Publishing publishing() default Publishing.NOT_SPECIFIED;
 
-
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The type-of the elements returned by the action.
      * @return
      */
+    // tag::refguide[]
     Class<?> typeOf() default Object.class;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Whether the action is restricted to prototyping.
      *
@@ -170,12 +174,10 @@ public @interface Action {
      *     By default there are no restrictions, with the action being available in all environments.
      * </p>
      */
+    // tag::refguide[]
     RestrictTo restrictTo() default RestrictTo.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Associates this action with a property or collection, specifying its id.
      *
@@ -195,8 +197,10 @@ public @interface Action {
      *     (in the Wicket UI, at least).
      * </p>
      */
+    // tag::refguide[]
     String associateWith() default "";
 
+    // end::refguide[]
     /**
      * Specifies the sequence/order in the UI for an action that's been associated with a property or collection.
      *
@@ -209,8 +213,10 @@ public @interface Action {
      *     For example <code>@Action(associateWith="items", associateWithSequence="2.1")</code>
      * </p>
      */
+    // tag::refguide[]
     String associateWithSequence() default "1";
 
+    // end::refguide[]
     /**
      * For uploading {@link Blob} or {@link Clob}, optionally restrict the files accepted (eg <tt>.xslx</tt>).
      *
@@ -220,5 +226,8 @@ public @interface Action {
      *
      * @see <a href="http://www.w3schools.com/tags/att_input_accept.asp">http://www.w3schools.com</a>
      */
+    // tag::refguide[]
     String fileAccept() default "";
-}
\ No newline at end of file
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ActionLayout.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ActionLayout.java
index ca1a3a7..8a6f370 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ActionLayout.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ActionLayout.java
@@ -32,13 +32,18 @@ import org.apache.isis.applib.layout.component.CssClassFaPosition;
 /**
  * Layout hints for actions.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.METHOD,
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Mixin(method = "act")
 public @interface ActionLayout {
 
-
+    // end::refguide[]
     /**
      * Whether (and how) this action can be bookmarked in the UI.
      *
@@ -48,10 +53,10 @@ public @interface ActionLayout {
      *     identically).
      * </p>
      */
+    // tag::refguide[]
     BookmarkPolicy bookmarking() default BookmarkPolicy.NOT_SPECIFIED;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates the css class that an action should have.
      *
@@ -59,47 +64,47 @@ public @interface ActionLayout {
      *     For the Wicket viewer, this can be a bootstrap class such as <code>btn-info</code>.
      * </p>
      */
+    // tag::refguide[]
     String cssClass() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a> CSS class to decorate an
      * action (button or menu item).
      */
+    // tag::refguide[]
     String cssClassFa() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates the position of the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a>
      * icon. The icon could be rendered on the left or the right of the action button
      */
+    // tag::refguide[]
     CssClassFaPosition cssClassFaPosition() default CssClassFaPosition.LEFT;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Description of this action, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates where in the UI the action should <i>not</i>not be visible.
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Name of this action (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * For actions that are associated with a property, indicates the positioning of the
      * action's button relative to the property.
@@ -108,6 +113,7 @@ public @interface ActionLayout {
      * Ignored if the action has not been associated with a property.
      * </p>
      */
+    // tag::refguide[]
     Position position() default Position.NOT_SPECIFIED;
 
     @XmlType(
@@ -121,22 +127,22 @@ public @interface ActionLayout {
         NOT_SPECIFIED
     }
 
+    // end::refguide[]
     /**
      * How this parameters for this action are prompted, either {@link PromptStyle#DIALOG dialog} or {@link PromptStyle#INLINE inline}.
      */
+    // tag::refguide[]
     PromptStyle promptStyle() default PromptStyle.AS_CONFIGURED;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * If the action returns its target, then determines whether to update the page or
      * instead to redirect (forcing a re-rendering of a new page).
      */
+    // tag::refguide[]
     Redirect redirectPolicy() default Redirect.AS_CONFIGURED;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * For actions of domain services that can be viewed and contributed (that is, whose
      * {@link DomainService#nature() nature} is either {@link org.apache.isis.applib.annotation.NatureOfService#VIEW}
@@ -147,7 +153,8 @@ public @interface ActionLayout {
      *     Has no meaning for actions of domain entities.
      * </p>
      */
+    // tag::refguide[]
     Contributed contributed() default Contributed.NOT_SPECIFIED;
 
-
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Auditing.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Auditing.java
index eb1f6f8..01fdf3c 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Auditing.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Auditing.java
@@ -21,7 +21,10 @@ package org.apache.isis.applib.annotation;
 /**
  * The available policies for auditing changes to the properties of the object.
  */
+// tag::refguide[]
 public enum Auditing {
+
+    // end::refguide[]
     /**
      * The auditing of the object should be as per the default auditing policy configured in <tt>application.properties</tt>.
      *
@@ -29,18 +32,30 @@ public enum Auditing {
      *     If no auditing policy is configured, then the auditing is disabled.
      * </p>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
+
+    // end::refguide[]
     /**
      * Audit changes to this object.
      */
+    // tag::refguide[]
     ENABLED,
+
+    // end::refguide[]
     /**
      * Do not audit changes to this object (even if otherwise configured to enable auditing).
      */
+    // tag::refguide[]
     DISABLED,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/BookmarkPolicy.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/BookmarkPolicy.java
index a310d85..a17a903 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/BookmarkPolicy.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/BookmarkPolicy.java
@@ -21,25 +21,40 @@ package org.apache.isis.applib.annotation;
 
 import javax.xml.bind.annotation.XmlType;
 
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum BookmarkPolicy {
+
+    // end::refguide[]
     /**
      * Can be bookmarked, and is a top-level 'root' (or parent) bookmark.
      */
+    // tag::refguide[]
     AS_ROOT,
+
+    // end::refguide[]
     /**
      * Can be bookmarked, but only as a child or some other parent/root bookmark
      */
+    // tag::refguide[]
     AS_CHILD,
+
+    // end::refguide[]
     /**
      * An unimportant entity that should never be bookmarked.
      */
+    // tag::refguide[]
     NEVER,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
-}
\ No newline at end of file
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Bounding.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Bounding.java
index fc33caa..4e18848 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Bounding.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Bounding.java
@@ -21,8 +21,10 @@ package org.apache.isis.applib.annotation;
 /**
  * Whether the set of instances of a domain object is bounded or not.
  */
+// tag::refguide[]
 public enum Bounding {
     BOUNDED,
     UNBOUNDED,
     NOT_SPECIFIED
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Collection.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Collection.java
index fa8944a..38a7d19 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Collection.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Collection.java
@@ -30,12 +30,19 @@ import org.apache.isis.applib.events.domain.CollectionDomainEvent;
 /**
  * Domain semantics for domain object collection.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.ANNOTATION_TYPE})
+@Target({
+        ElementType.METHOD,
+        ElementType.FIELD,
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Mixin(method = "coll")
 public @interface Collection {
 
+    // end::refguide[]
     /**
      * Indicates that changes to the collection that should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -56,18 +63,17 @@ public @interface Collection {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CollectionDomainEvent<?,?>> domainEvent() default CollectionDomainEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates when the collection is not visible to the user.
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Whether the properties of this domain object can be edited, or collections of this object be added to/removed from.
      *
@@ -75,36 +81,37 @@ public @interface Collection {
      *     Note that non-editable objects can nevertheless have actions invoked upon them.
      * </p>
      */
+    // tag::refguide[]
     Editing editing() default Editing.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * If {@link #editing()} is set to {@link Editing#DISABLED},
      * then the reason to provide to the user as to why this property cannot be edited.
      */
+    // tag::refguide[]
     String editingDisabledReason() default "";
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Indicates whether the collecion should be included or excluded from mementos.
      *
      * <p>
-     *     To ensure that the collection is actually not persisted in the objectstore, 
+     *     To ensure that the collection is actually not persisted in the objectstore,
      *     also annotate with the JDO annotation {@link javax.jdo.annotations.NotPersistent}.
      * </p>
      */
+    // tag::refguide[]
     MementoSerialization mementoSerialization() default MementoSerialization.NOT_SPECIFIED;
 
-
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The type-of the elements held within the collection.
+     *
      * @return
      */
+    // tag::refguide[]
     Class<?> typeOf() default Object.class;
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CollectionLayout.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CollectionLayout.java
index bc38db5..c061cbb 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CollectionLayout.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CollectionLayout.java
@@ -29,28 +29,33 @@ import java.util.Comparator;
 /**
  * Layout hints for collections.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.METHOD,
+        ElementType.FIELD,
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Mixin(method = "coll")
 public @interface CollectionLayout {
 
-
+    // end::refguide[]
     /**
      * Indicates the css class that a collection should have.
      */
+    // tag::refguide[]
     String cssClass() default "";
 
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Description of this collection, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates which view is used by default to render the collection.
      *
@@ -62,10 +67,10 @@ public @interface CollectionLayout {
      *     &quot;<a href="https://github.com/isisaddons/isis-wicket-gmap3">map</a>&quot;.
      * </p>
      */
+    // tag::refguide[]
     String defaultView() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates where in the UI the collection should <i>not</i>not be visible.
      *
@@ -74,24 +79,24 @@ public @interface CollectionLayout {
      *      apply for collections.
      * </p>
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Name of this collection (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * A flag indicating whether the value of {@linkplain #named()} should be HTML escaped or not.
      */
+    // tag::refguide[]
     boolean namedEscaped() default true;
 
+    // end::refguide[]
     /**
      * The page size for instances of this class when rendered within
      * a table.
@@ -104,13 +109,10 @@ public @interface CollectionLayout {
      * If annotated on a type, then the page size refers to standalone
      * collections (eg as returned from a repository query).
      */
+    // tag::refguide[]
     int paged() default -1;
 
-
-
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates that the elements in a ({@link java.util.SortedSet}) collection should be sorted according to a different order than the
      * natural sort order, as defined by the specified{@link java.util.Comparator}.
@@ -130,6 +132,8 @@ public @interface CollectionLayout {
      * may be sorted in an order more suitable to the context.
      */
     @SuppressWarnings("rawtypes")
+    // tag::refguide[]
     Class sortedBy() default Comparator.class;
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandExecuteIn.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandExecuteIn.java
index d416983..6aecd14 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandExecuteIn.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandExecuteIn.java
@@ -30,23 +30,24 @@ package org.apache.isis.applib.annotation;
  */
 // tag::refguide[]
 public enum CommandExecuteIn {
-// end::refguide[]
+
+    // end::refguide[]
     /**
      * Execute synchronously in the &quot;foreground&quot;, wait for the results.
      */
-// tag::refguide[]
+    // tag::refguide[]
     FOREGROUND,
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * Execute &quot;asynchronously&quot; through the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, returning (if possible) the
      * persisted {@link org.apache.isis.applib.services.command.Command command} object as a placeholder to the
      * result.
      */
-// tag::refguide[]
+    // tag::refguide[]
     BACKGROUND,
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * For commands that are replicated from a master onto a slave and are to be replayed (typically using the same
      * mechanism as "regular" background commands, eg a background job).
@@ -55,18 +56,19 @@ public enum CommandExecuteIn {
      *     For framework use, not intended to be used in application code.
      * </p>
      */
-// tag::refguide[]
+    // tag::refguide[]
     REPLAYABLE,
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * For commands that have been excluded and will not run.
      * These are typically for a replayable command that has hit an exception (which normally would prevent any further
      * replayable commands from being replayed) and which the administrator has decided to skip.
      */
-// tag::refguide[]
+    // tag::refguide[]
     EXCLUDED
-// end::refguide[]
+
+    // end::refguide[]
     ;
 
     public boolean isForeground() { return this == FOREGROUND; }
@@ -82,7 +84,7 @@ public enum CommandExecuteIn {
             private Meta() {}
         }
     }
+    // tag::refguide[]
 
-// tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandPersistence.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandPersistence.java
index b518f5a..635db744 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandPersistence.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandPersistence.java
@@ -23,34 +23,32 @@ package org.apache.isis.applib.annotation;
  */
 // tag::refguide[]
 public enum CommandPersistence {
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * (If the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
      * {@link org.apache.isis.applib.services.command.Command Command} object should be persisted.
      */
-// tag::refguide[]
+    // tag::refguide[]
     PERSISTED,
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * (If the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
      * {@link org.apache.isis.applib.services.command.Command Command} object should only be persisted if
      * another service, such as the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, hints that it should.
      */
-// tag::refguide[]
+    // tag::refguide[]
     IF_HINTED,
-// end::refguide[]
 
+    // end::refguide[]
     /**
      * (Even if the configured {@link org.apache.isis.applib.services.command.spi.CommandService} supports it), indicates that the
      * {@link org.apache.isis.applib.services.command.Command Command} object should <i>not</i> be persisted (even if
      * another service, such as the {@link org.apache.isis.applib.services.background.BackgroundCommandService}, hints that it should).
      */
-// tag::refguide[]
-    NOT_PERSISTED;
-// end::refguide[]
+    // tag::refguide[]
+    NOT_PERSISTED
 
-// tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandReification.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandReification.java
index 89edc33..32bef90 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandReification.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/CommandReification.java
@@ -21,7 +21,10 @@ package org.apache.isis.applib.annotation;
 /**
  * The available policies as to whether action invocations are reified into commands.
  */
+// tag::refguide[]
 public enum CommandReification {
+
+    // end::refguide[]
     /**
      * Whether the action should be handled as a command as per the default command configured in <tt>applicationp.properties</tt>.
      *
@@ -29,18 +32,30 @@ public enum CommandReification {
      *     If no command policy is configured, then the action is <i>not</i> treated as a command.
      * </p>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
+
+    // end::refguide[]
     /**
      * Handle the action as a command, irrespective of any configuration settings.
      */
+    // tag::refguide[]
     ENABLED,
+
+    // end::refguide[]
     /**
      * Do not handle the action as a command, irrespective of any configuration settings.
      */
+    // tag::refguide[]
     DISABLED,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Constants.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Constants.java
deleted file mode 100644
index c33615f..0000000
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Constants.java
+++ /dev/null
@@ -1,27 +0,0 @@
-/*
- *  Licensed to the Apache Software Foundation (ASF) under one
- *  or more contributor license agreements.  See the NOTICE file
- *  distributed with this work for additional information
- *  regarding copyright ownership.  The ASF licenses this file
- *  to you under the Apache License, Version 2.0 (the
- *  "License"); you may not use this file except in compliance
- *  with the License.  You may obtain a copy of the License at
- *
- *        http://www.apache.org/licenses/LICENSE-2.0
- *
- *  Unless required by applicable law or agreed to in writing,
- *  software distributed under the License is distributed on an
- *  "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY
- *  KIND, either express or implied.  See the License for the
- *  specific language governing permissions and limitations
- *  under the License.
- */
-
-package org.apache.isis.applib.annotation;
-
-public class Constants {
-
-    private Constants(){}
-
-    public static final String MENU_ORDER_DEFAULT = "" + (Integer.MAX_VALUE - 100);
-}
\ No newline at end of file
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Contributed.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Contributed.java
index 64cb43c..8859a28 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Contributed.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Contributed.java
@@ -24,32 +24,50 @@ import javax.xml.bind.annotation.XmlType;
 /**
  * The means by which a domain service action will be contributed to a domain object.
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum Contributed {
+
+    // end::refguide[]
     /**
      * Default: contributed as both an action and also (if takes a single argument and has safe semantics) as an association
      * (contributed property if returns a single value, contributed collection if returns a collection).
      */
+    // tag::refguide[]
     AS_BOTH,
+
+    // end::refguide[]
     /**
      * Contributed as an action but <i>not</i> as an association.
      */
+    // tag::refguide[]
     AS_ACTION,
+
+    // end::refguide[]
     /**
      * (If takes a single argument and has safe semantics) then is contributed as an association
      * (contributed property if returns a single value, contributed collection if returns a collection) but <i>not</i>
      * as an action.
      */
+    // tag::refguide[]
     AS_ASSOCIATION,
+
+    // end::refguide[]
     /**
      * The action is not contributed as either an action or as an association.
      */
+    // tag::refguide[]
     AS_NEITHER,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
-}
\ No newline at end of file
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Defaulted.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Defaulted.java
index 3cc72fc..ad4bc6f 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Defaulted.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Defaulted.java
@@ -48,11 +48,13 @@ import org.apache.isis.applib.adapters.DefaultsProvider;
  *     Note: This annotation is only incompletely recognized by the framework, and may be deprecated in the future.
  * </p>
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Defaulted {
 
+    // end::refguide[]
     /**
      * The fully qualified name of a class that implements the
      * {@link DefaultsProvider} interface.
@@ -66,8 +68,10 @@ public @interface Defaulted {
      * Implementation note: the default value provided here is simply an empty
      * string because <tt>null</tt> is not a valid default.
      */
+    // tag::refguide[]
     String defaultsProviderName() default "";
 
+    // end::refguide[]
     /**
      * As per {@link #defaultsProviderName()}, but specifying a class literal
      * rather than a fully qualified class name.
@@ -77,6 +81,8 @@ public @interface Defaulted {
      * {@link Defaulted}'s own class, because <tt>null</tt> is not a valid
      * default.
      */
+    // tag::refguide[]
     Class<?> defaultsProviderClass() default Defaulted.class;
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObject.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObject.java
index 785446f..bf5bee4 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObject.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObject.java
@@ -45,12 +45,17 @@ import org.apache.isis.applib.events.lifecycle.ObjectUpdatingEvent;
  * annotated type. 
  * For more details see <code>org.apache.isis.config.beans.IsisBeanFactoryPostProcessorForSpring</code>
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Component @Scope("prototype")
 public @interface DomainObject {
 
+    // end::refguide[]
     /**
      * Whether the entity should be audited (note: does not apply to view models or other recreatable objects.
      *
@@ -59,12 +64,10 @@ public @interface DomainObject {
      * registered with the framework.
      * </p>
      */
+    // tag::refguide[]
     Auditing auditing() default Auditing.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Whether changes to the object should be published.
      *
@@ -73,21 +76,20 @@ public @interface DomainObject {
      * registered with the framework.
      * </p>
      */
+    // tag::refguide[]
     Publishing publishing() default Publishing.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * The class of the domain service that provides an <code>autoComplete(String)</code> method.
      *
      * <p>
      * It is sufficient to specify an interface rather than a concrete type.
      */
+    // tag::refguide[]
     Class<?> autoCompleteRepository() default Object.class;
 
-
+    // end::refguide[]
     /**
      * The method (despite its name, not necessarily an action) to use in order to perform the auto-complete search
      * (defaults to &quot;autoComplete&quot;).
@@ -95,12 +97,10 @@ public @interface DomainObject {
      * <p>
      * The method is required to accept a single string parameter, and must return a list of the domain type.
      */
+    // tag::refguide[]
     String autoCompleteAction() default "autoComplete";
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Indicates that the class has a bounded, or finite, set of instances.
      *
@@ -113,12 +113,10 @@ public @interface DomainObject {
      * </p>
      *
      */
+    // tag::refguide[]
     Bounding bounding() default Bounding.NOT_SPECIFIED;
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Whether the properties of this domain object can be edited, or collections of this object be added to/removed from.
      *
@@ -126,19 +124,18 @@ public @interface DomainObject {
      *     Note that non-editable objects can nevertheless have actions invoked upon them.
      * </p>
      */
+    // tag::refguide[]
     Editing editing() default Editing.NOT_SPECIFIED;
 
-
+    // end::refguide[]
     /**
      * If {@link #editing()} is set to {@link Editing#DISABLED},
      * then the reason to provide to the user as to why the object's properties cannot be edited/collections modified.
      */
+    // tag::refguide[]
     String editingDisabledReason() default "Disabled";
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Provides a unique abbreviation for the object type, eg &quot;customer.Customer&quot; for Customer.
      *
@@ -147,19 +144,17 @@ public @interface DomainObject {
      * used by the framework to unique identify an object over time (same concept as a URN).
      * </p>
      */
+    // tag::refguide[]
     String objectType() default "";
 
-
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * The nature of this domain object.
      */
+    // tag::refguide[]
     Nature nature() default Nature.NOT_SPECIFIED;
 
-
-
+    // end::refguide[]
     /**
      * Equivalent to {@link Mixin#method()}.
      *
@@ -167,11 +162,10 @@ public @interface DomainObject {
      *     Applicable only if {@link #nature()} is {@link Nature#MIXIN}.
      * </p>
      */
+    // tag::refguide[]
     String mixinMethod() default Mixin.DEFAULT_METHOD_NAME;
 
-    // //////////////////////////////////////
-
-
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -181,8 +175,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectCreatedEvent<?>> createdLifecycleEvent() default ObjectCreatedEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -192,8 +188,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectPersistingEvent<?>> persistingLifecycleEvent() default ObjectPersistingEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -203,8 +201,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectPersistedEvent<?>> persistedLifecycleEvent() default ObjectPersistedEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -214,8 +214,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectLoadedEvent<?>> loadedLifecycleEvent() default ObjectLoadedEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -225,8 +227,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectUpdatingEvent<?>> updatingLifecycleEvent() default ObjectUpdatingEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -236,9 +240,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectUpdatedEvent<?>> updatedLifecycleEvent() default ObjectUpdatedEvent.Default.class;
 
-
+    // end::refguide[]
     /**
      * Indicates that the loading of the domain object should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -248,9 +253,10 @@ public @interface DomainObject {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ObjectRemovingEvent<?>> removingLifecycleEvent() default ObjectRemovingEvent.Default.class;
 
-
+    // end::refguide[]
     /**
      * Indicates that an invocation of <i>any</i> action of the domain object (that do not themselves specify their own
      * <tt>&#64;Action(domainEvent=...)</tt> should be posted to the
@@ -278,8 +284,10 @@ public @interface DomainObject {
      * It must also use <tt>Object</tt> as its generic type.  This is to allow mixins to also emit the same event.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends ActionDomainEvent<?>> actionDomainEvent() default ActionDomainEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that changes to <i>any</i> property of the domain object (that do not themselves specify their own
      * <tt>&#64;Property(domainEvent=...)</tt> should be posted to the
@@ -302,8 +310,10 @@ public @interface DomainObject {
      * It must also use <tt>Object</tt> as its generic type.  This is to allow mixins to also emit the same event.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends PropertyDomainEvent<?,?>> propertyDomainEvent() default PropertyDomainEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates that changes to <i>any</i> collection of the domain object (that do not themselves specify their own
      * <tt>&#64;Collection(domainEvent=...)</tt>  should be posted to the
@@ -325,6 +335,8 @@ public @interface DomainObject {
      * It must also use <tt>Object</tt> as its generic type.  This is to allow mixins to also emit the same event.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CollectionDomainEvent<?,?>> collectionDomainEvent() default CollectionDomainEvent.Default.class;
 
-}
\ No newline at end of file
+}
+// end::refguide[]
\ No newline at end of file
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObjectLayout.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObjectLayout.java
index 73344ce..b1360a8 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObjectLayout.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainObjectLayout.java
@@ -34,12 +34,16 @@ import org.apache.isis.applib.layout.component.CssClassFaPosition;
 /**
  * Layout hints for domain objects.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface DomainObjectLayout {
 
-
+    // end::refguide[]
     /**
      * Which subclass of {@link TitleUiEvent} should be used to obtain a title.
      *
@@ -47,10 +51,10 @@ public @interface DomainObjectLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends TitleUiEvent<?>> titleUiEvent() default TitleUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link IconUiEvent} should be used to obtain an icon.
      *
@@ -58,10 +62,10 @@ public @interface DomainObjectLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends IconUiEvent<?>> iconUiEvent() default IconUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link CssClassUiEvent} should be used to obtain a CSS class.
      *
@@ -69,10 +73,10 @@ public @interface DomainObjectLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CssClassUiEvent<?>> cssClassUiEvent() default CssClassUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link LayoutUiEvent} should be used to obtain a layout.
      *
@@ -80,21 +84,25 @@ public @interface DomainObjectLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends LayoutUiEvent<?>> layoutUiEvent() default LayoutUiEvent.Default.class;
 
+    // end::refguide[]
     /**
      * Indicates the css class that a domain class (type) should have.
      */
+    // tag::refguide[]
     String cssClass() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a> CSS class to decorate an
      * domain object.
      */
+    // tag::refguide[]
     String cssClassFa() default "";
 
+    // end::refguide[]
     /**
      * Indicates the position of the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a>
      * icon. The icon could be rendered on the left or the right of the object's title.
@@ -103,27 +111,24 @@ public @interface DomainObjectLayout {
      *     This attribute is currently ignored by Isis viewers.
      * </p>
      */
+    // tag::refguide[]
     CssClassFaPosition cssClassFaPosition() default CssClassFaPosition.LEFT;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Description of this class, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Name of this class (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The page size for instances of this class when rendered within
      * a table.
@@ -136,21 +141,22 @@ public @interface DomainObjectLayout {
      * If annotated on a type, then the page size refers to standalone
      * collections (eg as returned from a repository query).
      */
+    // tag::refguide[]
     int paged() default -1;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The plural name of the class.
      */
+    // tag::refguide[]
     String plural() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Whether (and how) this domain object can be bookmarked in the UI.
      */
+    // tag::refguide[]
     BookmarkPolicy bookmarking() default BookmarkPolicy.NOT_SPECIFIED;
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainService.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainService.java
index e836635..02b2cee 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainService.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainService.java
@@ -41,21 +41,34 @@ import org.springframework.stereotype.Service;
  * For more details see {@link org.apache.isis.config.beans.IsisBeanFactoryPostProcessorForSpring}.
  * 
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Service @Singleton
 public @interface DomainService {
 
+    // end::refguide[]
     /**
      * Provides the (first part of the) unique identifier (OID) for the service (the instanceId is always &quot;1&quot;).
      *
      * <p>
      * If not specified then either the optional &quot;getId()&quot is used, otherwise the class' name.
      */
+    // tag::refguide[]
     String objectType() default "";
 
+    // end::refguide[]
+    /**
+     * The nature of this service, eg for menus, contributed actions, repository.
+     */
+    // tag::refguide[]
+    NatureOfService nature() default NatureOfService.VIEW;
 
+    // end::refguide[]
     /**
      * If this domain service acts as a repository for an entity type, specify that entity type.
      * @deprecated was never implemented
@@ -63,10 +76,6 @@ public @interface DomainService {
     @Deprecated
     Class<?> repositoryFor() default Object.class;
 
-    /**
-     * The nature of this service, eg for menus, contributed actions, repository.
-     */
-    NatureOfService nature() default NatureOfService.VIEW;
-
-
+    // tag::refguide[]
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainServiceLayout.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainServiceLayout.java
index abc7fc1..a3342fe 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainServiceLayout.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/DomainServiceLayout.java
@@ -32,14 +32,20 @@ import java.lang.annotation.Target;
  * Also indicates the name, and menu ordering UI hints.
  * </p>
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface DomainServiceLayout {
 
+    // end::refguide[]
     /**
      * Name of this class (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
     public enum MenuBar {
@@ -49,12 +55,15 @@ public @interface DomainServiceLayout {
         NOT_SPECIFIED
     }
 
+    // end::refguide[]
     /**
      * The menubar in which the menu that holds this service's actions should reside.
      */
+    // tag::refguide[]
     MenuBar menuBar() default MenuBar.NOT_SPECIFIED;
 
-    //TODO[2140] DomainServiceLayout 
+    // end::refguide[]
+    //TODO[2140] DomainServiceLayout
     //    /**
     //     * Number in Dewey Decimal format representing the order.
     //     *
@@ -78,4 +87,8 @@ public @interface DomainServiceLayout {
     //     * </p>
     //     */
     //    String menuOrder() default Constants.MENU_ORDER_DEFAULT;
+
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Editing.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Editing.java
index 9404bc4..32c1761 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Editing.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Editing.java
@@ -21,7 +21,10 @@ package org.apache.isis.applib.annotation;
 /**
  * The available policies for editing properties and collections.
  */
+// tag::refguide[]
 public enum Editing {
+
+    // end::refguide[]
     /**
      * The editing of the object should be as per the default editing policy configured in <tt>application.properties</tt>.
      *
@@ -29,19 +32,30 @@ public enum Editing {
      *     If no editing policy is configured, then the editing is enabled.
      * </p>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
+
+    // end::refguide[]
     /**
      * Audit changes to this object.
      */
+    // tag::refguide[]
     ENABLED,
+
+    // end::refguide[]
     /**
      * Do not allow the properties to be edited, or the collections to be added to/removed from.
      */
+    // tag::refguide[]
     DISABLED,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/EqualByContent.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/EqualByContent.java
index afaf0ad..b907f48 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/EqualByContent.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/EqualByContent.java
@@ -57,8 +57,13 @@ import java.util.HashMap;
  *     Note: This annotation is only incompletely recognized by the framework, and may be deprecated in the future.
  * </p>
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.METHOD })
+@Target({
+        ElementType.TYPE,
+        ElementType.METHOD
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface EqualByContent {
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Facets.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Facets.java
index db68ad0..8be974f 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Facets.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Facets.java
@@ -33,10 +33,13 @@ import java.lang.annotation.Target;
  * At least one named factory (as per {@link #facetFactoryNames()}) or one class
  * factory (as per {@link #facetFactoryClasses()}) should be specified.
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Facets {
+
+    // end::refguide[]
     /**
      * Array of fully qualified names of classes each implementing
      * <tt>org.apache.isis.core.metamodel.facets.FacetFactory</tt>.
@@ -45,8 +48,10 @@ public @interface Facets {
      * Either the array provided by this method or by
      * {@link #facetFactoryClasses()} should be non-empty.
      */
+    // tag::refguide[]
     String[] facetFactoryNames() default {};
 
+    // end::refguide[]
     /**
      * Array of {@link Class}s, each indicating a class implementing
      * <tt>org.apache.isis.core.metamodel.facets.FacetFactory</tt>.
@@ -55,6 +60,8 @@ public @interface Facets {
      * Either the array provided by this method or by
      * {@link #facetFactoryNames()} should be non-empty.
      */
+    // tag::refguide[]
     Class<?>[] facetFactoryClasses() default {};
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/HomePage.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/HomePage.java
index fbc757f..014f8e5 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/HomePage.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/HomePage.java
@@ -34,8 +34,10 @@ import java.lang.annotation.Target;
  *     to traverse or operate on the rendered state.
  * </p>
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface HomePage {
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/LabelPosition.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/LabelPosition.java
index 99abea8..5ac5aa1 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/LabelPosition.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/LabelPosition.java
@@ -26,23 +26,30 @@ import javax.xml.bind.annotation.XmlType;
  * @see org.apache.isis.applib.annotation.PropertyLayout
  * @see org.apache.isis.applib.annotation.ParameterLayout
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum LabelPosition {
+
     DEFAULT,
     LEFT,
-
+    // end::refguide[]
     /**
      * Right position of the label for Boolean properties.
      * <strong>Not supported</strong> for now for other types.
      */
+    // tag::refguide[]
     RIGHT,
     TOP,
     NONE,
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MemberOrder.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MemberOrder.java
index 659f1a2..eef7938 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MemberOrder.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MemberOrder.java
@@ -33,11 +33,13 @@ import java.lang.annotation.Target;
  *     where <code>Xxx</code> is the domain object name.
  * </p>
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.METHOD, ElementType.FIELD })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface MemberOrder {
 
+    // end::refguide[]
     /**
      * Groups or associate members with each other.
      *
@@ -47,13 +49,17 @@ public @interface MemberOrder {
      *     <li>For collections, currently has no meaning</li>
      * </ul>
      */
+    // tag::refguide[]
     String name() default "";
 
+    // end::refguide[]
     /**
      * The order of this member relative to other members in the same group, in
      * Dewey-decimal notation.  For collections this is relative to each other
      * (collections aren't grouped).
      */
+    // tag::refguide[]
     String sequence();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MementoSerialization.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MementoSerialization.java
index 9f79818..a4f9410 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MementoSerialization.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MementoSerialization.java
@@ -21,12 +21,18 @@ package org.apache.isis.applib.annotation;
 /**
  * Whether the property or collection is included if the domain object is serialized into a memento.
  */
+// tag::refguide[]
 public enum MementoSerialization {
+
+    // end::refguide[]
     /**
      * Property or collection is included in any mementos.
      * This is the fallback/default if not explicitly excluded.
      */
+    // tag::refguide[]
     INCLUDED,
+
+    // end::refguide[]
     /**
      * Property or collection's state is excluded from any mementos.
      *
@@ -34,10 +40,16 @@ public enum MementoSerialization {
      *     Corresponds to <tt>@Property(notPersisted=true)</tt> or <tt>@Collection(notPersisted=true)</tt> prior to Isis 2.x
      * </p>
      */
+    // tag::refguide[]
     EXCLUDED,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MinLength.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MinLength.java
index 77bba48..469a0e3 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MinLength.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/MinLength.java
@@ -28,10 +28,11 @@ import java.lang.annotation.Target;
 /**
  * Specify the minimum number of characters for an autocomplete search argument.
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.PARAMETER })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface MinLength {
-
     int value();
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Mixin.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Mixin.java
index 5e47907..5d8d41c 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Mixin.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Mixin.java
@@ -36,17 +36,21 @@ import org.springframework.stereotype.Component;
  * annotated type. 
  * For more details see {@link org.apache.isis.config.beans.IsisBeanFactoryPostProcessorForSpring}.
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 @Component @Scope("prototype")
 public @interface Mixin {
 
+    // end::refguide[]
     /**
      * The default of {@link Mixin#method()}).
      */
+    // tag::refguide[]
     String DEFAULT_METHOD_NAME = "$$";
 
+    // end::refguide[]
     /**
      * Specifies the name of the verb to use within the mixin, eg "exec", "invoke", "apply" and so on,
      *
@@ -64,6 +68,8 @@ public @interface Mixin {
      *     valid identifiers after Java 8.
      * </p>
      */
+    // tag::refguide[]
     String method() default DEFAULT_METHOD_NAME;
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Module.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Module.java
index 7b7887f..b9e82b3 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Module.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Module.java
@@ -49,6 +49,7 @@ import org.springframework.context.annotation.Import;
  *             scanning more classes than are needed.  It is therefore not used within the framework code, but is
  *             provided as a convenience by domain applications.
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
@@ -56,5 +57,5 @@ import org.springframework.context.annotation.Import;
 @Documented
 @ComponentScan
 public @interface Module {
-
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Nature.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Nature.java
index df64918..b044747 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Nature.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Nature.java
@@ -28,15 +28,19 @@ import javax.xml.bind.annotation.XmlRootElement;
  *     difference is one of intent.
  * </p>
  */
+// tag::refguide[]
 public enum Nature {
 
+    // end::refguide[]
     /**
      * The default; allows the programmer to combine <tt>@DomainObject</tt> annotation with the
      * {@link ViewModel} annotation, or the {@link XmlRootElement} annotation, or by implementing the
      * {@link org.apache.isis.applib.ViewModel} interface.
      */
+    // tag::refguide[]
     NOT_SPECIFIED,
 
+    // end::refguide[]
     /**
      * A domain entity whose persistence is managed internally by Isis, using JDO as the persistence implementation.
      * Domain entities are considered to be part of the domain model layer.
@@ -49,7 +53,10 @@ public enum Nature {
      *    Currently implies no additional semantics other than documentation.
      * </p>
      */
+    // tag::refguide[]
     JDO_ENTITY,
+
+    // end::refguide[]
     /**
      * A domain entity that is a wrapper/proxy/stub to some externally managed entity.  Domain entities are
      * considered to be part of the domain model layer.
@@ -64,15 +71,18 @@ public enum Nature {
      *     {@link XmlRootElement} annotation instead.
      * </p>
      */
+    // tag::refguide[]
     EXTERNAL_ENTITY,
+
+    // end::refguide[]
     /**
      * A domain entity that is a wrapper/proxy/stub to a &quot;synthetic&quot; entity, for example one that is
      * constructed from some sort of internal memory data structure.
      *
      * <p>
-     *     As for a {@link #EXTERNAL_ENTITY}, the identity of a synthetic entity is determined solely by the 
+     *     As for a {@link #EXTERNAL_ENTITY}, the identity of a synthetic entity is determined solely by the
      *     state of object's properties (that have not been set to be ignored using
-     *     {@link org.apache.isis.applib.annotation.Property#notPersisted()}).
+     *     {@link Property#mementoSerialization()}).
      * </p>
      *
      * <p>
@@ -80,7 +90,10 @@ public enum Nature {
      *     {@link XmlRootElement} annotation instead.
      * </p>
      */
+    // tag::refguide[]
     INMEMORY_ENTITY,
+
+    // end::refguide[]
     /**
      * An object that is conceptually part of the application layer, and which surfaces behavior and/or state that
      * is aggregate of one or more domain entity.
@@ -100,20 +113,26 @@ public enum Nature {
      *
      * @see ViewModel
      */
+    // tag::refguide[]
     VIEW_MODEL,
 
+    // end::refguide[]
     /**
      * An object that acts as a mix-in to some other object, contributing behavior and/or derived state based on the
      * domain object.
      *
      * @see Mixin
      */
+    // tag::refguide[]
     MIXIN,
-    
+
+    // end::refguide[]
     /**
-     * An object that is entirely managed by the underlying IoC container. 
+     * An object that is entirely managed by the underlying IoC container.
      * @apiNote EXPERIMENTAL
      */
+    // tag::refguide[]
     BEAN,
-    
+
 }
+// tag::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/NatureOfService.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/NatureOfService.java
index f02c2aa..77ad2d9 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/NatureOfService.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/NatureOfService.java
@@ -22,23 +22,32 @@ package org.apache.isis.applib.annotation;
  * The different sorts of domain services recognized by Isis, as specified in {@link DomainService#nature()}
  * 
  */
+// tag::refguide[]
 public enum NatureOfService {
 
+    // end::refguide[]
     /**
      * The service's actions appear in the REST API and in 'viewers', eg. in the menu bar.
-     * 
+     *
      * @apiNote
      * Contributing actions to the 'viewer' implies, that these must also be exposed to the REST API,
-     * simply because alternative viewers might be solely based on the provided REST end-points.  
+     * simply because alternative viewers might be solely based on the provided REST end-points.
      */
+    // tag::refguide[]
     VIEW,
 
+    // end::refguide[]
     /**
      * The service's actions should only be visible in the REST API exposed by the Restful Objects viewer.
      */
+    // tag::refguide[]
     REST,
-    
+
+    // end::refguide[]
+
+    //
     // -- DEPRECATIONS
+    //
 
     /**
      * A <em>programmatic</em> service.
@@ -59,21 +68,21 @@ public enum NatureOfService {
      */
     @Deprecated
     VIEW_REST_ONLY,
-    
+
     /**
      * @deprecated will be removed with 2.0.0 release! use {@link #VIEW} instead
      * @apiNote For now, used as synonym for {@link #VIEW}
      */
     @Deprecated
     VIEW_MENU_ONLY,
-    
+
     /**
      * @deprecated will be removed with 2.0.0 release!
      * <p>
-     * For now, contributing actions will be gathered to show up in the 'others' menu to ease migration. 
+     * For now, contributing actions will be gathered to show up in the 'others' menu to ease migration.
      * These will likely not work.
      * <p>
-     * Migration Note: For each {@code Action} write a new mixin class. 
+     * Migration Note: For each {@code Action} write a new mixin class.
      * see {@link Mixin}
      * @apiNote For now, used as synonym for {@link #VIEW}
      */
@@ -90,7 +99,7 @@ public enum NatureOfService {
     public boolean isView() {
         return this == VIEW || this == VIEW_MENU_ONLY  || this == VIEW_CONTRIBUTIONS_ONLY;
     }
-    
+
     /**
      * Whether a service contributes its actions exclusively to the REST API.
      * @see {@link NatureOfService#REST}
@@ -98,7 +107,7 @@ public enum NatureOfService {
     public boolean isRestOnly() {
         return this == REST || this == VIEW_REST_ONLY;
     }
-    
+
     /**
      * Whether a service contributes no actions at all.
      * @see {@link NatureOfService#DOMAIN}
@@ -116,7 +125,7 @@ public enum NatureOfService {
         return isRestOnly() || isView();
     }
 
-
-
+    // tag::refguide[]
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Navigable.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Navigable.java
index 6daac44..d4ba91e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Navigable.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Navigable.java
@@ -26,19 +26,20 @@ package org.apache.isis.applib.annotation;
  * @since 2.0
  *
  */
+// tag::refguide[]
 public enum Navigable {
 
-
     NOT_SPECIFIED,
-
     IGNORE,
-
     PARENT,
-
+    // end::refguide[]
     ;
 
     public boolean isParent() {
         return this == PARENT;
     }
 
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Optionality.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Optionality.java
index e3efad5..9389e42 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Optionality.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Optionality.java
@@ -21,30 +21,39 @@ package org.apache.isis.applib.annotation;
 /**
  * Whether the property or parameter is optional or is required (aka mandatory).
  */
+// tag::refguide[]
 public enum Optionality {
+
+    // end::refguide[]
     /**
      * Default, usually meaning mandatory for properties and always meaning mandatory for parameters.
      *
      * <p>
-     * For properties, will be false unless JDO {@link javax.jdo.annotations.Column} has also specified with
-     * {@link javax.jdo.annotations.Column#allowsNull()} set to <code>true</code>.
+     * For properties, will be false unless JDO <code>javax.jdo.annotations.Column</code> has also specified with
+     * <code>javax.jdo.annotations.Column#allowsNull()</code> set to <code>true</code>.
      * </p>
      */
+    // tag::refguide[]
     DEFAULT,
+
+    // end::refguide[]
     /**
      * Indicates that the property or parameter is not required.
      */
+    // tag::refguide[]
     OPTIONAL,
+
+    // end::refguide[]
     /**
-     * Indicates that the property is required (even if the JDO {@link javax.jdo.annotations.Column} annotation
+     * Indicates that the property is required (even if the JDO <code>javax.jdo.annotations.Column</code> annotation
      * says otherwise).
      *
      * <p>
      * When using the JDO/DataNucleus objectstore, it is sometimes necessary to annotate a property as optional
-     * (using {@link javax.jdo.annotations.Column#allowsNull()} set to <code>true</code>), even if the property is
+     * (using <code>javax.jdo.annotations.Column#allowsNull()</code> set to <code>true</code>), even if the property is
      * logically mandatory.  For example, this can occur when the property is in a subtype class that has been
-     * "rolled up" to the superclass table using {@link javax.jdo.annotations.Inheritance} with the
-     * {@link javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE superclass}<tt> strategy.
+     * "rolled up" to the superclass table using <code>javax.jdo.annotations.Inheritance</code>> with the
+     * <code>javax.jdo.annotations.InheritanceStrategy#SUPERCLASS_TABLE</code> superclass strategy.
      * </p>
      *
      * <p>
@@ -53,10 +62,16 @@ public enum Optionality {
      * is unable to do so.
      * </p>
      */
+    // tag::refguide[]
     MANDATORY,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/OrderPrecedence.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/OrderPrecedence.java
index 7751a58..e4caea8 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/OrderPrecedence.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/OrderPrecedence.java
@@ -27,6 +27,7 @@ import lombok.experimental.UtilityClass;
 @UtilityClass
 public class OrderPrecedence {
 
+    // end::refguide[]
     /**
      * For domain services with the highest precedence value.
      * No framework services use this constant, but some very fundamental services (eg for security)
@@ -35,28 +36,40 @@ public class OrderPrecedence {
      * @see java.lang.Integer#MIN_VALUE
      * @see Ordered#HIGHEST_PRECEDENCE
      */
+    // tag::refguide[]
     public static final int FIRST = Ordered.HIGHEST_PRECEDENCE;
 
+    // end::refguide[]
     /**
      * For framework for services that are unlikely to be overridden by application code.
      */
+    // tag::refguide[]
     public static final int EARLY = FIRST / 2;
+
+    // end::refguide[]
     /**
      * For framework for services that could be overridden by application code (though not commonly).
      */
+    // tag::refguide[]
     public static final int MIDPOINT = 0;
+
+    // end::refguide[]
     /**
      * For framework services that are expected to be overridden by application code, or that act as a fallback.
      */
+    // tag::refguide[]
     public static final int LATE = OrderPrecedence.LAST / 2;
 
+    // end::refguide[]
     /**
      * For domain services that act as a fallback, and which will typically be overridden.
      *
      * @see java.lang.Integer#MAX_VALUE
      * @see Ordered#LOWEST_PRECEDENCE
      */
+    // tag::refguide[]
     public static final int LAST = Ordered.LOWEST_PRECEDENCE;
 
 }
 // end::refguide[]
+
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Parameter.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Parameter.java
index 718908c..149a336 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Parameter.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Parameter.java
@@ -32,13 +32,16 @@ import org.apache.isis.applib.value.Clob;
 /**
  * Domain semantics for domain object collection.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.PARAMETER, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.PARAMETER,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Parameter {
 
-
-
+    // end::refguide[]
     /**
      * The maximum entry length of a field.
      *
@@ -46,10 +49,10 @@ public @interface Parameter {
      *     The default value (<code>-1</code>) indicates that no maxLength has been specified.
      * </p>
      */
+    // tag::refguide[]
     int maxLength() default -1;
 
-
-
+    // end::refguide[]
     /**
      * Whether this parameter is optional or is mandatory (ie required).
      *
@@ -58,10 +61,10 @@ public @interface Parameter {
      *     to mean that the parameter is required.
      * </p>
      */
+    // tag::refguide[]
     Optionality optionality() default Optionality.NOT_SPECIFIED;
 
-
-
+    // end::refguide[]
     /**
      * The {@link org.apache.isis.applib.spec.Specification}(s) to be satisfied by this parameter.
      *
@@ -69,15 +72,17 @@ public @interface Parameter {
      * If more than one is provided, then all must be satisfied (in effect &quot;AND&quot;ed together).
      * </p>
      */
+    // tag::refguide[]
     Class<? extends Specification>[] mustSatisfy() default {};
 
-
-
+    // end::refguide[]
     /**
      * Regular expression pattern that a value should conform to, and can be formatted as.
      */
+    // tag::refguide[]
     String regexPattern() default "";
 
+    // end::refguide[]
     /**
      * Pattern flags, as per {@link java.util.regex.Pattern#compile(String, int)} .
      *
@@ -85,14 +90,17 @@ public @interface Parameter {
      *     The default value, <code>0</code>, means that no flags have been specified.
      * </p>
      */
+    // tag::refguide[]
     int regexPatternFlags() default 0;
 
+    // end::refguide[]
     /**
      * Replacement text for the pattern in generated error message.
      */
+    // tag::refguide[]
     String regexPatternReplacement() default "Doesn't match pattern";
 
-
+    // end::refguide[]
     /**
      * For uploading {@link Blob} or {@link Clob}, optionally restrict the files accepted (eg <tt>.xslx</tt>).
      *
@@ -102,6 +110,8 @@ public @interface Parameter {
      *
      * @see <a href="http://www.w3schools.com/tags/att_input_accept.asp">http://www.w3schools.com</a>
      */
+    // tag::refguide[]
     String fileAccept() default "";
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ParameterLayout.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ParameterLayout.java
index 60bf10c..782b3a6 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ParameterLayout.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ParameterLayout.java
@@ -30,21 +30,30 @@ import java.lang.annotation.Target;
  *
  * @see org.apache.isis.applib.annotation.PropertyLayout
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.PARAMETER, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.PARAMETER,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ParameterLayout {
 
+    // end::refguide[]
     /**
      * Indicates the css class that a parameter should have.
      */
+    // tag::refguide[]
     String cssClass() default "";
 
+    // end::refguide[]
     /**
      * Description of this property, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
+    // end::refguide[]
     /**
      * In forms, positioning of the label (left, top or none) relative to the parameter value.
      *
@@ -52,23 +61,31 @@ public @interface ParameterLayout {
      * If not specified, the default depends upon the parameter value's datatype.
      * </p>
      */
+    // tag::refguide[]
     LabelPosition labelPosition() default LabelPosition.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * Name of this action parameter.
      */
+    // tag::refguide[]
     String named() default "";
 
+    // end::refguide[]
     /**
      * A flag indicating whether the value of {@linkplain #named()} should be HTML escaped or not.
      */
+    // tag::refguide[]
     boolean namedEscaped() default true;
 
+    // end::refguide[]
     /**
      * For string parameters (and properties), whether to render as a text area over multiple lines.
      */
+    // tag::refguide[]
     int multiLine() default -1;
 
+    // end::refguide[]
     /**
      * For date parameters (and properties) only, instructs the viewer that the date should be rendered as one day
      * prior to the actually stored date.
@@ -93,12 +110,15 @@ public @interface ParameterLayout {
      * In the domain object, itself, however, the value stored is 1-jun-2013.
      * </p>
      */
+    // tag::refguide[]
     RenderDay renderDay() default RenderDay.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * The typical entry length of a field, use to determine the optimum width for display
      */
+    // tag::refguide[]
     int typicalLength() default -1;
 
 }
-
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Programmatic.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Programmatic.java
index ce61dc7..215bf43 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Programmatic.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Programmatic.java
@@ -38,14 +38,15 @@ import java.lang.annotation.Target;
  * It can also be added to a type, meaning that the type is ignored from the metamodel.
  * This is intended as a &quot;get out of jail&quot; for any classes from unit tests, say,
  * that end up on the classpath of integration tests but should otherwise be ignored.
- *
- * <p>
- * This is intended as a replacement for {@link Ignore} (the use of which is
- * being discouraged because of the name clash with <tt>org.junit.Ignore</tt>).
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.TYPE, ElementType.FIELD })
+@Target({
+        ElementType.METHOD,
+        ElementType.TYPE,
+        ElementType.FIELD
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Programmatic {
-
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Projecting.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Projecting.java
index ce231ce..82b7a74 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Projecting.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Projecting.java
@@ -18,14 +18,22 @@
  */
 package org.apache.isis.applib.annotation;
 
+// tag::refguide[]
 public enum Projecting {
 
+    // end::refguide[]
     /**
      * The property holds the underlying domain object of which this (view model) object is a projection.
      */
+    // tag::refguide[]
     PROJECTED,
+
+    // end::refguide[]
     /**
      * The property
      */
+    // tag::refguide[]
     NOT_SPECIFIED;
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PromptStyle.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PromptStyle.java
index 2c6d6da..bbe9e1b 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PromptStyle.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PromptStyle.java
@@ -23,10 +23,13 @@ import javax.xml.bind.annotation.XmlType;
 /**
  * How prompting for new values of a property/arguments for an action should be performed
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum PromptStyle {
+
+    // end::refguide[]
     /**
      * Prompt using the style configured by <tt>isis.viewer.wicket.promptStyle</tt>.
      *
@@ -34,7 +37,10 @@ public enum PromptStyle {
      *      If no style is configured, then {@link #INLINE} is assumed.
      * </p>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
+
+    // end::refguide[]
     /**
      * Use a dialog for the prompt.
      *
@@ -44,19 +50,31 @@ public enum PromptStyle {
      *     <code>isis.viweer.wicket.dialogMode</code> configuration property.
      * </p>
      */
+    // tag::refguide[]
     DIALOG,
+
+    // end::refguide[]
     /**
      * Use a dialog for the prompt, rendered in a sidebar.
      */
+    // tag::refguide[]
     DIALOG_SIDEBAR,
+
+    // end::refguide[]
     /**
      * Use a dialog for the prompt, rendered in a modal dialog.
      */
+    // tag::refguide[]
     DIALOG_MODAL,
+
+    // end::refguide[]
     /**
      * Show the form inline, temporarily replacing the rendering of the property.
      */
+    // tag::refguide[]
     INLINE,
+
+    // end::refguide[]
     /**
      * Applies only to actions, show the form inline, invoked as if editing the property.
      *
@@ -76,16 +94,23 @@ public enum PromptStyle {
      * </p>
      *
      */
+    // tag::refguide[]
     INLINE_AS_IF_EDIT,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED;
 
+    // end::refguide[]
     public boolean isDialog() { return this == DIALOG || this == DIALOG_MODAL || this == DIALOG_SIDEBAR; }
     public boolean isInline() { return this == INLINE; }
     public boolean isInlineAsIfEdit() { return this == INLINE_AS_IF_EDIT; }
-
     public boolean isInlineOrInlineAsIfEdit() { return this == INLINE || this == INLINE_AS_IF_EDIT; }
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Property.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Property.java
index bd774db..df31640 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Property.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Property.java
@@ -38,15 +38,19 @@ import org.apache.isis.applib.value.Clob;
 /**
  * Domain semantics for domain object property.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.METHOD,
+        ElementType.FIELD,
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
-
-//@Action(semantics=SemanticsOf.SAFE)   
-//@ActionLayout(contributed=Contributed.AS_ASSOCIATION)
 @Mixin(method = "prop")
 public @interface Property {
 
+    // end::refguide[]
     /**
      * Indicates that changes to the property that should be posted to the
      * {@link org.apache.isis.applib.services.eventbus.EventBusService event bus} using a custom (subclass of)
@@ -66,17 +70,17 @@ public @interface Property {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends PropertyDomainEvent<?,?>> domainEvent() default PropertyDomainEvent.Default.class;
 
-
-
-
-
+    // end::refguide[]
     /**
      * Indicates where the property is not visible to the user.
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * If set to {@link Projecting#PROJECTED projected}, then indicates that the owner of this property is a view model
      * which is a projection of some other entity, and that the property holds a reference to that
@@ -91,11 +95,10 @@ public @interface Property {
      *     Only one such property should be marked as being a projection with a view model.
      * </p>
      */
+    // tag::refguide[]
     Projecting projecting() default Projecting.NOT_SPECIFIED;
 
-
-
-
+    // end::refguide[]
     /**
      * Whether the properties of this domain object can be edited, or collections of this object be added to/removed from.
      *
@@ -103,29 +106,32 @@ public @interface Property {
      *     Note that non-editable objects can nevertheless have actions invoked upon them.
      * </p>
      */
+    // tag::refguide[]
     Editing editing() default Editing.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * If {@link #editing()} is set to {@link Editing#DISABLED},
      * then the reason to provide to the user as to why this property cannot be edited.
      */
+    // tag::refguide[]
     String editingDisabledReason() default "";
 
-
-
-
-
+    // end::refguide[]
     /**
      * Whether the property edit should be reified into a {@link org.apache.isis.applib.services.command.Command} object.
      */
     CommandReification command() default CommandReification.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * How the {@link org.apache.isis.applib.services.command.Command Command} object provided by the
      * {@link org.apache.isis.applib.services.command.CommandContext CommandContext} domain service should be persisted.
      */
+    // tag::refguide[]
     CommandPersistence commandPersistence() default CommandPersistence.PERSISTED;
 
+    // end::refguide[]
     /**
      * How the command/property edit should be executed.
      *
@@ -135,10 +141,10 @@ public @interface Property {
      * will be set to this value.
      * </p>
      */
+    // tag::refguide[]
     CommandExecuteIn commandExecuteIn() default CommandExecuteIn.FOREGROUND;
 
-
-
+    // end::refguide[]
     /**
      * Whether the property edit should be published.
      *
@@ -147,9 +153,10 @@ public @interface Property {
      * or {@link org.apache.isis.applib.services.publish.PublisherService} is registered with the framework.
      * </p>
      */
+    // tag::refguide[]
     Publishing publishing() default Publishing.NOT_SPECIFIED;
 
-
+    // end::refguide[]
     /**
      * The {@link CommandDtoProcessor} to process this command's DTO.
      *
@@ -164,11 +171,10 @@ public @interface Property {
      *     {@link ContentMappingServiceForCommandsDto} to dynamically transform the DTOs.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CommandDtoProcessor> commandDtoProcessor() default CommandDtoProcessor.class;
 
-
-
-
+    // end::refguide[]
     /**
      * The maximum entry length of a field.
      *
@@ -176,12 +182,10 @@ public @interface Property {
      *     The default value (<code>-1</code>) indicates that no maxLength has been specified.
      * </p>
      */
+    // tag::refguide[]
     int maxLength() default -1;
 
-
-
-
-
+    // end::refguide[]
     /**
      * The {@link org.apache.isis.applib.spec.Specification}(s) to be satisfied by this property.
      *
@@ -189,45 +193,42 @@ public @interface Property {
      * If more than one is provided, then all must be satisfied (in effect &quot;AND&quot;ed together).
      * </p>
      */
+    // tag::refguide[]
     Class<? extends Specification>[] mustSatisfy() default {};
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates whether the property should be included or excluded from mementos.
      *
      * <p>
-     *     To ensure that the property is actually not persisted in the objectstore, also annotate with the JDO annotation 
-     *     {@link javax.jdo.annotations.NotPersistent}.
+     *     To ensure that the property is actually not persisted in the objectstore, also annotate with the JDO annotation
+     *     <code>javax.jdo.annotations.NotPersistent</code>
      * </p>
      */
+    // tag::refguide[]
     MementoSerialization mementoSerialization() default MementoSerialization.NOT_SPECIFIED;
 
-
-
-
-
+    // end::refguide[]
     /**
      * Whether this property is optional or is mandatory (ie required).
      *
      * <p>
      *     For properties the default value, {@link org.apache.isis.applib.annotation.Optionality#DEFAULT}, usually
      *     means that the property is required unless it has been overridden by {@link javax.jdo.annotations.Column}
-     *     with its {@link javax.jdo.annotations.Column#allowsNull() allowsNull()} attribute set to true.
+     *     with its <code>javax.jdo.annotations.Column#allowsNull()</code> attribute set to true.
      * </p>
      */
+    // tag::refguide[]
     Optionality optionality() default Optionality.NOT_SPECIFIED;
 
-
-
-
-
+    // end::refguide[]
     /**
      * Regular expression pattern that a value should conform to, and can be formatted as.
      */
+    // tag::refguide[]
     String regexPattern() default "";
 
+    // end::refguide[]
     /**
      * Pattern flags, as per {@link java.util.regex.Pattern#compile(String, int)} .
      *
@@ -235,17 +236,17 @@ public @interface Property {
      *     The default value, <code>0</code>, means that no flags have been specified.
      * </p>
      */
+    // tag::refguide[]
     int regexPatternFlags() default 0;
 
+    // end::refguide[]
     /**
      * Replacement text for the pattern in generated error message.
      */
+    // tag::refguide[]
     String regexPatternReplacement() default "Doesn't match pattern";
 
-
-
-
-
+    // end::refguide[]
     /**
      * For uploading {@link Blob} or {@link Clob}, optionally restrict the files accepted (eg <tt>.xslx</tt>).
      *
@@ -255,7 +256,8 @@ public @interface Property {
      *
      * @see <a href="http://www.w3schools.com/tags/att_input_accept.asp">http://www.w3schools.com</a>
      */
+    // tag::refguide[]
     String fileAccept() default "";
 
-
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PropertyLayout.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PropertyLayout.java
index edd145d..11f965b 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PropertyLayout.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PropertyLayout.java
@@ -30,28 +30,35 @@ import java.lang.annotation.Target;
  *
  * @see org.apache.isis.applib.annotation.ParameterLayout
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.METHOD, ElementType.FIELD, ElementType.TYPE, ElementType.ANNOTATION_TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 @Mixin(method = "prop")
 public @interface PropertyLayout {
 
+    // end::refguide[]
     /**
      * Indicates the css class that a property should have.
      */
+    // tag::refguide[]
     String cssClass() default "";
 
+    // end::refguide[]
     /**
      * Description of this property, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
-
+    // end::refguide[]
     /**
      * Indicates where in the UI the property should <i>not</i>not be visible.
      */
+    // tag::refguide[]
     Where hidden() default Where.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * In forms, positioning of the label (left, top or none) relative to the property value.
      *
@@ -59,30 +66,41 @@ public @interface PropertyLayout {
      * If not specified, the default depends upon the property value's datatype.
      * </p>
      */
+    // tag::refguide[]
     LabelPosition labelPosition() default LabelPosition.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * For string properties (and parameters), render as a text area over specified number of lines.
      */
+    // tag::refguide[]
     int multiLine() default -1;
 
+    // end::refguide[]
     /**
      * Name of this property (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
+    // end::refguide[]
     /**
      * A flag indicating whether the value of {@linkplain #named()} should be HTML escaped or not.
      */
+    // tag::refguide[]
     boolean namedEscaped() default true;
 
+    // tag::refguide[]
     Navigable navigable() default Navigable.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * How the properties of this domain object are be edited, either {@link PromptStyle#DIALOG dialog} or {@link PromptStyle#INLINE inline}.
      */
+    // tag::refguide[]
     PromptStyle promptStyle() default PromptStyle.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * For date properties (and parameters) only, instructs the viewer that the date should be rendered as one day
      * prior to the actually stored date.
@@ -108,13 +126,17 @@ public @interface PropertyLayout {
      * In the domain object, itself, however, the value stored is 1-jun-2013.
      * </p>
      */
+    // tag::refguide[]
     RenderDay renderDay() default RenderDay.NOT_SPECIFIED;
 
+    // end::refguide[]
     /**
      * The typical entry length of a field, use to determine the optimum width for display
      */
+    // tag::refguide[]
     int typicalLength() default -1;
 
+    // end::refguide[]
     /**
      * Indicates that the value held by the property never changes over time, even when other properties of the object
      * do change.
@@ -137,7 +159,9 @@ public @interface PropertyLayout {
      *     within the framework than simply a hint for rendering.
      * </p>
      */
+    // tag::refguide[]
     Repainting repainting() default Repainting.NOT_SPECIFIED;
 
 }
+// end::refguide[]
 
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Publishing.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Publishing.java
index 581bdab..0afa406 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Publishing.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Publishing.java
@@ -21,7 +21,10 @@ package org.apache.isis.applib.annotation;
 /**
  * The available policies for publishing changes to the properties of the object.
  */
+// tag::refguide[]
 public enum Publishing {
+
+    // end::refguide[]
     /**
      * The publishing of the object should be as per the default publishing policy configured in <tt>application.properties</tt>.
      *
@@ -29,18 +32,30 @@ public enum Publishing {
      *     If no publishing policy is configured, then the publishing is disabled.
      * </p>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
+
+    // end::refguide[]
     /**
      * Publish changes to this object.
      */
+    // tag::refguide[]
     ENABLED,
+
+    // end::refguide[]
     /**
      * Do not publish changes to this object (even if otherwise configured to enable publishing).
      */
+    // tag::refguide[]
     DISABLED,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PublishingChangeKind.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PublishingChangeKind.java
index c7f7be7..48eba88 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PublishingChangeKind.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/PublishingChangeKind.java
@@ -18,8 +18,14 @@
  */
 package org.apache.isis.applib.annotation;
 
+// tag::refguide[]
 public enum PublishingChangeKind {
+
     CREATE,
+
     UPDATE,
-    DELETE;
+
+    DELETE,
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Redirect.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Redirect.java
index fe999c8..20d1e38 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Redirect.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Redirect.java
@@ -24,20 +24,27 @@ import javax.xml.bind.annotation.XmlType;
  * The available policies for rendering the next page if the result is the same as the target
  * (in other words, an action that returns "this").
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum Redirect {
+
+    // end::refguide[]
     /**
      * As defined by configuration property <code>isis.viewer.wicket.redirectEvenIfSameObject</code>
      */
+    // tag::refguide[]
     AS_CONFIGURED,
 
+    // end::refguide[]
     /**
      * Redirect (meaning render a new page) even if the result of the action is the same as the target.
      */
+    // tag::refguide[]
     EVEN_IF_SAME,
 
+    // end::refguide[]
     /**
      * Don't redirect if the result is the same as the target, instead just update the existing page.
      *
@@ -45,5 +52,8 @@ public enum Redirect {
      *     Of course, a redirect is still performed if the result of the action is different from the target.
      * </p>
      */
+    // tag::refguide[]
     ONLY_IF_DIFFERS,
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/RenderDay.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/RenderDay.java
index b5b60cd..15d79ed 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/RenderDay.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/RenderDay.java
@@ -23,18 +23,28 @@ import javax.xml.bind.annotation.XmlType;
 /**
  * How to render days.
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum RenderDay {
+
     AS_DAY,
+
+    // end::refguide[]
     /**
      * Equivalent to <tt>@PropertyLayout(renderAsDayBefore=true)</tt> prior to Isis 2.x
      */
+    // tag::refguide[]
     AS_DAY_BEFORE,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
-    NOT_SPECIFIED;
+    // tag::refguide[]
+    NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Repainting.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Repainting.java
index ffc0052..ed7c88e 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Repainting.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Repainting.java
@@ -23,18 +23,28 @@ import javax.xml.bind.annotation.XmlType;
 /**
  * Whether a component is unchanging and so does not require repainting.
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum Repainting {
+
     REPAINT,
+
+    // end::refguide[]
     /**
      * Equivalent to <tt>@PropertyLayout(unchanging=true)</tt> prior to Isis 2.x
      */
+    // tag::refguide[]
     NO_REPAINT,
+
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
+    // tag::refguide[]
     NOT_SPECIFIED
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/RestrictTo.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/RestrictTo.java
index 801939f..b7b395d 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/RestrictTo.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/RestrictTo.java
@@ -21,8 +21,14 @@ package org.apache.isis.applib.annotation;
 /**
  * Whether an action is restricted to development mode, or available in all.
  */
+// tag::refguide[]
 public enum RestrictTo {
+
     PROTOTYPING,
+
     NO_RESTRICTIONS,
+
     NOT_SPECIFIED;
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/SemanticsOf.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/SemanticsOf.java
index 553f2c7..49a0436 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/SemanticsOf.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/SemanticsOf.java
@@ -23,53 +23,63 @@ import org.apache.isis.applib.util.Enums;
 /**
  * @see <a href="https://isis.apache.org/guides/rgant/rgant.html#_rgant-Action_semantics">Reference Guide</a>
  */
+// tag::refguide[]
 public enum SemanticsOf {
 
+    // end::refguide[]
     /**
      * Safe, with no side effects, and caching the returned value when invoked multiple times in the same request.
      * <ul>
      * <li>Changes state: <b>No</b></li>
      * <li>HTTP verb: <b>GET</b></li>
-     * <li>Effect of multiple calls: Will <b>always return the same result</b> each time invoked 
+     * <li>Effect of multiple calls: Will <b>always return the same result</b> each time invoked
      * (within a given request scope).</li>
      * </ul>
      */
+    // tag::refguide[]
     SAFE_AND_REQUEST_CACHEABLE,
 
+    // end::refguide[]
     /**
      * Safe, with no side-effects. In other words, a query-only action.
      * <ul>
      * <li>Changes state: <b>No</b></li>
      * <li>HTTP verb: <b>GET</b></li>
-     * <li>Effect of multiple calls: Might result in <b>different results each invocation</b> 
+     * <li>Effect of multiple calls: Might result in <b>different results each invocation</b>
      * (within a given request scope).</li>
      * </ul>
      */
+    // tag::refguide[]
     SAFE,
 
+    // end::refguide[]
     /**
      * Post-conditions are always the same, irrespective as to how many times called.
      * <ul>
      * <li>Changes state: <b>Yes</b></li>
      * <li>HTTP verb: <b>PUT</b></li>
-     * <li>Effect of multiple calls: Will make <b>no further changes</b> if called multiple times 
+     * <li>Effect of multiple calls: Will make <b>no further changes</b> if called multiple times
      * (eg sets a property or adds of same item to a Set).</li>
      * </ul>
      */
+    // tag::refguide[]
     IDEMPOTENT,
 
+    // end::refguide[]
     /**
      * Neither safe nor idempotent; every invocation is likely to change the state of the object.
      * <ul>
      * <li>Changes state: <b>Yes</b></li>
      * <li>HTTP verb: <b>POST</b></li>
-     * <li>Effect of multiple calls: Might <b>change the state</b> of the system each time called 
+     * <li>Effect of multiple calls: Might <b>change the state</b> of the system each time called
      * (eg increments a counter or adds to a List).</li>
      * <li>Example: Increasing the quantity of a line item in an Order by 1.</li>
      * </ul>
      */
+    // tag::refguide[]
     NON_IDEMPOTENT,
 
+    // end::refguide[]
     /**
      * Post-conditions are always the same, irrespective as to how many times called.
      * <p>
@@ -77,12 +87,14 @@ public enum SemanticsOf {
      * <ul>
      * <li>Changes state: <b>Yes</b></li>
      * <li>HTTP verb: <b>PUT</b></li>
-     * <li>Effect of multiple calls: Will make <b>no further changes</b> if called multiple times 
+     * <li>Effect of multiple calls: Will make <b>no further changes</b> if called multiple times
      * (eg sets a property or adds of same item to a Set).</li>
      * </ul>
      */
+    // tag::refguide[]
     IDEMPOTENT_ARE_YOU_SURE,
 
+    // end::refguide[]
     /**
      * Neither safe nor idempotent; every invocation is likely to change the state of the object.
      * <p>
@@ -90,17 +102,23 @@ public enum SemanticsOf {
      * <ul>
      * <li>Changes state: <b>Yes</b></li>
      * <li>HTTP verb: <b>POST</b></li>
-     * <li>Effect of multiple calls: Might <b>change the state</b> of the system each time called 
+     * <li>Effect of multiple calls: Might <b>change the state</b> of the system each time called
      * (eg increments a counter or adds to a List).</li>
      * <li>Example: Increasing the quantity of a line item in an Order by 1.</li>
      */
+    // tag::refguide[]
     NON_IDEMPOTENT_ARE_YOU_SURE,
 
+    // end::refguide[]
     /**
      * Ignore the value provided by this annotation (meaning that the framework will keep searching, in meta
      * annotations or superclasses/interfaces).
      */
-    NOT_SPECIFIED;
+    // tag::refguide[]
+    NOT_SPECIFIED
+
+    // end::refguide[]
+    ;
 
     public String getFriendlyName() {
         return Enums.getFriendlyNameOf(this);
@@ -140,4 +158,7 @@ public enum SemanticsOf {
         return this == IDEMPOTENT_ARE_YOU_SURE || this == NON_IDEMPOTENT_ARE_YOU_SURE;
     }
 
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Title.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Title.java
index f7c3259..b6cd0c1 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Title.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Title.java
@@ -28,30 +28,44 @@ import java.lang.annotation.Target;
  * A title annotation used to annotate methods used to construct the title of a
  * domain object instance. It is used as a marker.
  */
+// tag::refguide[]
 @Retention(RetentionPolicy.RUNTIME)
-@Target({ ElementType.METHOD, ElementType.FIELD })
+@Target({
+        ElementType.METHOD,
+        ElementType.FIELD
+})
 public @interface Title {
 
+    // end::refguide[]
     /**
      * The order (in Dewey decimal notation) that the property annotated with
      * {@link Title} appears with respect to other properties also annotated
      * with {@link Title}.
      */
+    // tag::refguide[]
     String sequence() default "1.0";
 
+    // end::refguide[]
     /**
      * The string to use to separate this property from any preceding properties
      * in the title.
      */
+    // tag::refguide[]
     String prepend() default " ";
 
+    // end::refguide[]
     /**
      * The string to append to this property if non-empty.
      */
+    // tag::refguide[]
     String append() default "";
 
+    // end::refguide[]
     /**
      * The length to abbreviate this title element to.
      */
+    // tag::refguide[]
     int abbreviatedTo() default Integer.MAX_VALUE;
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Value.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Value.java
index 03e8dd2..446bf84 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Value.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Value.java
@@ -54,11 +54,13 @@ import org.apache.isis.applib.adapters.ValueSemanticsProvider;
  *     Note: This annotation is only incompletely recognized by the framework, and may be deprecated in the future.
  * </p>
  */
+// tag::refguide[]
 @Inherited
 @Target({ ElementType.TYPE })
 @Retention(RetentionPolicy.RUNTIME)
 public @interface Value {
 
+    // end::refguide[]
     /**
      * The fully qualified name of a class that implements the
      * {@link ValueSemanticsProvider} interface.
@@ -82,8 +84,10 @@ public @interface Value {
      * Implementation note: the default value provided here is simply an empty
      * string because <tt>null</tt> is not a valid default.
      */
+    // tag::refguide[]
     String semanticsProviderName() default "";
 
+    // end::refguide[]
     /**
      * As per {@link #semanticsProviderName()}, but specifying a class literal
      * rather than a fully qualified class name.
@@ -92,6 +96,8 @@ public @interface Value {
      * Implementation note: the default value provided here is simply the
      * {@link Value}'s own class, because <tt>null</tt> is not a valid default.
      */
+    // tag::refguide[]
     Class<?> semanticsProviderClass() default Value.class;
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ViewModel.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ViewModel.java
index e76c9d2..8c4b8c7 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ViewModel.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ViewModel.java
@@ -51,14 +51,18 @@ import org.springframework.stereotype.Component;
  * @see ViewModel
  * 
  * @apiNote Meta annotation {@link Component} allows for the Spring framework to pick up (discover) the 
- * annotated type. 
- * For more details see {@link org.apache.isis.config.beans.IsisBeanFactoryPostProcessorForSpring}.
+ * annotated type.
+ *
+ * For more details see <code>org.apache.isis.config.beans.IsisBeanFactoryPostProcessorForSpring</code>.
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 @Component @Scope("prototype")
 public @interface ViewModel {
-
-
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ViewModelLayout.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ViewModelLayout.java
index f2972f8..c748e84 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ViewModelLayout.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/ViewModelLayout.java
@@ -46,11 +46,16 @@ import org.apache.isis.applib.layout.component.CssClassFaPosition;
  *      with just <tt>@ViewModel</tt> and <tt>@ViewModelLayout</tt>.
  * </p>
  */
+// tag::refguide[]
 @Inherited
-@Target({ ElementType.TYPE, ElementType.ANNOTATION_TYPE })
+@Target({
+        ElementType.TYPE,
+        ElementType.ANNOTATION_TYPE
+})
 @Retention(RetentionPolicy.RUNTIME)
 public @interface ViewModelLayout {
 
+    // end::refguide[]
     /**
      * Which subclass of {@link TitleUiEvent} should be used to obtain a title.
      *
@@ -58,10 +63,10 @@ public @interface ViewModelLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends TitleUiEvent<?>> titleUiEvent() default TitleUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link IconUiEvent} should be used to obtain an icon.
      *
@@ -69,10 +74,10 @@ public @interface ViewModelLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends IconUiEvent<?>> iconUiEvent() default IconUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link CssClassUiEvent} should be used to obtain a CSS class.
      *
@@ -80,10 +85,10 @@ public @interface ViewModelLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends CssClassUiEvent<?>> cssClassUiEvent() default CssClassUiEvent.Default.class;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Which subclass of {@link LayoutUiEvent} should be used to obtain a layout.
      *
@@ -91,22 +96,25 @@ public @interface ViewModelLayout {
      * This subclass must provide a no-arg constructor; the fields are set reflectively.
      * </p>
      */
+    // tag::refguide[]
     Class<? extends LayoutUiEvent<?>> layoutUiEvent() default LayoutUiEvent.Default.class;
 
-
+    // end::refguide[]
     /**
      * Indicates the css class that a domain class (type) should have.
      */
+    // tag::refguide[]
     String cssClass() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Indicates the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a> CSS class to decorate an
      * domain object.
      */
+    // tag::refguide[]
     String cssClassFa() default "";
 
+    // end::refguide[]
     /**
      * Indicates the position of the <a href="http://fortawesome.github.io/Font-Awesome/">Font Awesome</a>
      * icon. The icon could be rendered on the left or the right of the object's title.
@@ -115,26 +123,24 @@ public @interface ViewModelLayout {
      *     This attribute is currently ignored by Isis viewers.
      * </p>
      */
+    // tag::refguide[]
     CssClassFaPosition cssClassFaPosition() default CssClassFaPosition.LEFT;
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Description of this class, eg to be rendered in a tooltip.
      */
+    // tag::refguide[]
     String describedAs() default "";
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Name of this class (overriding the name derived from its name in code).
      */
+    // tag::refguide[]
     String named() default "";
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The page size for instances of this class when rendered within
      * a table.
@@ -147,21 +153,22 @@ public @interface ViewModelLayout {
      * If annotated on a type, then the page size refers to standalone
      * collections (eg as returned from a repository query).
      */
+    // tag::refguide[]
     int paged() default -1;
 
-
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * The plural name of the class.
      */
+    // tag::refguide[]
     String plural() default "";
 
-    // //////////////////////////////////////
-
+    // end::refguide[]
     /**
      * Whether (and how) this domain object can be bookmarked in the UI.
      */
+    // tag::refguide[]
     BookmarkPolicy bookmarking() default BookmarkPolicy.NOT_SPECIFIED;
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Where.java b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Where.java
index 497b111..c1d01c2 100644
--- a/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Where.java
+++ b/api/applib/src/main/adoc/modules/applib-ant/examples/annotation/Where.java
@@ -40,41 +40,63 @@ import org.apache.isis.applib.util.Enums;
  * This enum is also used internally within the framework.  When rendering an element,
  * the framework developer should only use those values that represent concrete locations.
  */
+// tag::refguide[]
 @XmlType(
         namespace = "http://isis.apache.org/applib/layout/component"
         )
 public enum Where {
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden everywhere.
      *
      * <p>
      * Synonym for {@link #ANYWHERE}.
      */
+    // tag::refguide[]
     EVERYWHERE {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return true;
         }
+
+        // tag::refguide[]
+        // ...
     },
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden everywhere.
      *
      * <p>
      * Synonym for {@link #EVERYWHERE}.
      */
+    // tag::refguide[]
     ANYWHERE {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return true;
         }
+
+        // tag::refguide[]
+        // ...
     },
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden when displayed within an object form.
      *
      * <p>
      * For most viewers, this applies to property and collection members, not actions.
      */
+    // tag::refguide[]
     OBJECT_FORMS,
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden when displayed as a column of a table
      * within parent object's collection, and references that parent.
@@ -82,7 +104,10 @@ public enum Where {
      * <p>
      * For most (all?) viewers, this will have meaning only if applied to a property member.
      */
+    // tag::refguide[]
     REFERENCES_PARENT,
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden when displayed as a column of a table within
      * a parent object's collection.
@@ -90,7 +115,10 @@ public enum Where {
      * <p>
      * For most (all?) viewers, this will have meaning only if applied to a property member.
      */
+    // tag::refguide[]
     PARENTED_TABLES ,
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden when displayed as a column of a table showing a standalone list
      * of objects, for example as returned by a repository query.
@@ -98,7 +126,10 @@ public enum Where {
      * <p>
      * For most (all?) viewers, this will have meaning only if applied to a property member.
      */
+    // tag::refguide[]
     STANDALONE_TABLES,
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden when displayed as a column of a table, either an object's
      * collection or a standalone list.
@@ -106,24 +137,40 @@ public enum Where {
      * <p>
      * This combines {@link #PARENTED_TABLES} and {@link #STANDALONE_TABLES}.
      */
+    // tag::refguide[]
     ALL_TABLES {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return context == this || context == PARENTED_TABLES || context == STANDALONE_TABLES;
         }
+
+        // tag::refguide[]
+        // ...
     },
+
+    // end::refguide[]
     /**
      * The member should be disabled/hidden except when displayed as a column of a standalone table.
      *
      * <p>
      * This is the inverse of {@link #STANDALONE_TABLES}.
      */
+    // tag::refguide[]
     ALL_EXCEPT_STANDALONE_TABLES {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return context != STANDALONE_TABLES;
         }
+
+        // tag::refguide[]
+        // ...
     },
+
+    // end::refguide[]
     /**
      * To act as an override if a member would normally be hidden as a result of some other convention.
      *
@@ -131,22 +178,37 @@ public enum Where {
      * For example, if a property is annotated with <tt>@Title</tt>, then normally this should be hidden
      * from all tables.  Additionally annotating with <tt>@Hidden(where=Where.NOWHERE)</tt> overrides this.
      */
+    // tag::refguide[]
     NOWHERE {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return false;
         }
+
+        // tag::refguide[]
+        // ...
     },
+
+    // end::refguide[]
     /**
      * Acts as the default no-op value for {@link PropertyLayout#hidden()}, {@link CollectionLayout#hidden()} and {@link ActionLayout#hidden()}.
      */
+    // tag::refguide[]
     NOT_SPECIFIED {
+        // end::refguide[]
+
         @Override
         public boolean includes(Where context) {
             return false;
         }
+
+        // tag::refguide[]
+        // ...
     };
 
+    // end::refguide[]
     public String getFriendlyName() {
         return Enums.getFriendlyNameOf(this);
     }
@@ -169,4 +231,7 @@ public enum Where {
         return context == this;
     }
 
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/EventObjectBase.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/EventObjectBase.java
similarity index 89%
rename from api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/EventObjectBase.java
rename to api/applib/src/main/adoc/modules/applib-cm/examples/events/EventObjectBase.java
index 06a9edb..2cee75b 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/EventObjectBase.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/EventObjectBase.java
@@ -16,7 +16,7 @@
  *  specific language governing permissions and limitations
  *  under the License.
  */
-package org.apache.isis.applib.events.domain;
+package org.apache.isis.applib.events;
 
 import javax.annotation.Nullable;
 
@@ -27,36 +27,44 @@ import static org.apache.isis.core.commons.internal.base._With.requires;
 /**
  * @since 2.0
  */
+// tag::refguide[]
 public abstract class EventObjectBase<T> {
 
+    // end::refguide[]
     /**
      * The object on which the Event initially occurred.
      */
+    // tag::refguide[]
     protected transient T source;
 
+    // end::refguide[]
     /**
      * Constructs a prototypical Event.
      *
      * @param    source    The object on which the Event initially occurred.
      */
+    // tag::refguide[]
     protected EventObjectBase(@Nullable T source) {
         this.source = source;
     }
 
+    // end::refguide[]
     /**
      * The object on which the Event initially occurred.
      *
      * @return   The object on which the Event initially occurred.
      */
+    // tag::refguide[]
     public @Nullable T getSource() {
         return source;
     }
-    
+
+    // end::refguide[]
     /**
      * A one-shot function. Only allowed to be called if a source has not already been set.
-     * 
+     *
      * @apiNote reserved for framework internal use
-     * 
+     *
      * @param source non-null
      */
     public void initSource(T source) {
@@ -75,5 +83,7 @@ public abstract class EventObjectBase<T> {
     public String toString() {
         return getClass().getName() + "[source=" + source + "]";
     }
-    
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/AbstractDomainEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/AbstractDomainEvent.java
index 16aef719..4ca383c 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/AbstractDomainEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/AbstractDomainEvent.java
@@ -23,19 +23,24 @@ import java.util.Map;
 
 import org.apache.isis.applib.Identifier;
 import org.apache.isis.applib.annotation.Programmatic;
+import org.apache.isis.applib.events.EventObjectBase;
 import org.apache.isis.applib.services.command.CommandContext;
 import org.apache.isis.applib.services.i18n.TranslatableString;
 import org.apache.isis.applib.util.ObjectContracts;
 import org.apache.isis.applib.util.ToString;
 import org.apache.isis.core.commons.internal.exceptions._Exceptions;
 
+import lombok.Getter;
+
+// tag::refguide[]
 public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
 
+    // end::refguide[]
     /**
      * If used then the framework will set state via (non-API) setters.
      *
      * <p>
-     *     Because the {@link EventObjectBase} superclass prohibits a null source, 
+     *     Because the {@link EventObjectBase} superclass prohibits a null source,
      *     a dummy value is temporarily used.
      * </p>
      */
@@ -50,16 +55,14 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         this.identifier = identifier;
     }
 
-    // - mixedIn
-
-    private Object mixedIn;
-
     /**
      * Populated only for mixins; holds the underlying domain object that the mixin contributes to.
      */
-    public Object getMixedIn() {
-        return mixedIn;
-    }
+    // tag::refguide[]
+    @Getter
+    private Object mixedIn;
+
+    // end::refguide[]
     /**
      * Not API - set by the framework.
      */
@@ -68,28 +71,32 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
     }
 
 
-
-    // -- Subject
-
     /**
      * The subject of the event, which will be either the {@link #getSource() source} for a regular action, or the
      * {@link #getMixedIn() mixed-in} domain object for a mixin.
      */
+    // tag::refguide[]
     public Object getSubject() {
         final Object mixedIn = getMixedIn();
         return mixedIn != null ? mixedIn : getSource();
     }
 
-
-
-    // -- Phase
-
+    // end::refguide[]
+    // tag::refguide-1[]
     public enum Phase {
+
         HIDE,
+
         DISABLE,
+
         VALIDATE,
+
         EXECUTING,
-        EXECUTED;
+
+        EXECUTED
+
+        // end::refguide-1[]
+        ;
 
         /**
          * The significance being that at this point the proposed values/arguments are known, and so the event can be
@@ -114,34 +121,35 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         public boolean isExecuted() {
             return this == EXECUTED;
         }
-    }
+        // tag::refguide-1[]
 
-    private Phase phase;
+    }
+    // end::refguide-1[]
 
     /**
      * Whether the framework is checking visibility, enablement, validity or actually executing (invoking action,
      * updating property or collection).
      */
-    public Phase getEventPhase() {
-        return phase;
-    }
+    // tag::refguide[]
+    @Getter
+    private Phase eventPhase;
 
+    // end::refguide[]
     /**
      * Not API, set by the framework.
      */
     public void setEventPhase(Phase phase) {
-        this.phase = phase;
+        this.eventPhase = phase;
     }
 
-    // -- identifier
     /**
      * If the no-arg constructor is used, then the framework will populate this field reflectively.
      */
+    // tag::refguide[]
+    @Getter
     private Identifier identifier;
-    public Identifier getIdentifier() {
-        return identifier;
-    }
 
+    // end::refguide[]
     /**
      * Not API, set by the framework if the no-arg constructor is used.
      */
@@ -149,98 +157,117 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         this.identifier = identifier;
     }
 
-
-    // -- hide, isHidden
+    @Getter
     private boolean hidden;
-    public boolean isHidden() {
-        return hidden;
-    }
 
     /**
      * @see #veto(String, Object...)
      */
+    // tag::refguide[]
     public void hide() {
+        // end::refguide[]
+
         this.hidden = true;
-    }
 
+        // tag::refguide[]
+        // ...
+    }
+    // end::refguide[]
 
-    // -- disable, isDisabled, getDisabledReason, getDisabledReasonTranslatable
+    /**
+     * If {@link #isDisabled() disabled}, then either this method returns non-null or {@link #getDisabledReasonTranslatable()} will.
+     */
+    @Getter
     private String disabledReason;
 
+    /**
+     * If {@link #isDisabled() disabled}, then either this method returns non-null or {@link #getDisabledReason()} will.
+     */
+    @Getter
+    private TranslatableString disabledReasonTranslatable;
+
     public boolean isDisabled() {
         return disabledReason != null || disabledReasonTranslatable != null;
     }
 
-    /**
-     * If {@link #isDisabled() disabled}, then either this method returns non-null or {@link #getDisabledReasonTranslatable()} will.
-     */
-    public String getDisabledReason() {
-        return disabledReason;
-    }
 
     /**
      * @see #disable(org.apache.isis.applib.services.i18n.TranslatableString)
      * @see #veto(String, Object...)
      */
+    // tag::refguide[]
     public void disable(final String reason) {
+        // end::refguide[]
+
         this.disabledReason = reason;
-    }
 
-    private TranslatableString disabledReasonTranslatable;
-    /**
-     * If {@link #isDisabled() disabled}, then either this method returns non-null or {@link #getDisabledReason()} will.
-     */
-    public TranslatableString getDisabledReasonTranslatable() {
-        return disabledReasonTranslatable;
+        // tag::refguide[]
+        // ...
     }
+    // end::refguide[]
+
     /**
      * @see #disable(java.lang.String)
      * @see #veto(org.apache.isis.applib.services.i18n.TranslatableString)
      */
+    // tag::refguide[]
     public void disable(final TranslatableString reason) {
-        this.disabledReasonTranslatable = reason;
-    }
+        // end::refguide[]
 
+        this.disabledReasonTranslatable = reason;
 
-    // -- invalidate, isInvalid, getInvalidityReason, getInvalidityReasonTranslatable
-    private String invalidatedReason;
-    public boolean isInvalid() {
-        return invalidatedReason != null || invalidatedReasonTranslatable != null;
+        // tag::refguide[]
+        // ...
     }
+    // end::refguide[]
+
 
     /**
      * If {@link #isInvalid() invalid}, then either this method returns non-null or {@link #getInvalidityReasonTranslatable()} will.
      */
-    public String getInvalidityReason() {
-        return invalidatedReason;
+    @Getter
+    private String invalidityReason;
+
+    /**
+     * If {@link #isInvalid() invalid}, then either this method returns non-null or {@link #getInvalidityReason()} will.
+     */
+    @Getter
+    private TranslatableString invalidityReasonTranslatable;
+
+    public boolean isInvalid() {
+        return invalidityReason != null || invalidityReasonTranslatable != null;
     }
+
     /**
      * @see #invalidate(org.apache.isis.applib.services.i18n.TranslatableString)
      * @see #veto(String, Object...)
      */
+    // tag::refguide[]
     public void invalidate(final String reason) {
-        this.invalidatedReason = reason;
-    }
+        // end::refguide[]
 
-    private TranslatableString invalidatedReasonTranslatable;
-    /**
-     * If {@link #isInvalid() invalid}, then either this method returns non-null or {@link #getInvalidityReason()} will.
-     */
-    public TranslatableString getInvalidityReasonTranslatable() {
-        return invalidatedReasonTranslatable;
+        this.invalidityReason = reason;
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * @see #invalidate(String)
      * @see #veto(org.apache.isis.applib.services.i18n.TranslatableString)
      */
+    // tag::refguide[]
     public void invalidate(final TranslatableString reason) {
-        this.invalidatedReasonTranslatable = reason;
-    }
+        // end::refguide[]
 
+        this.invalidityReasonTranslatable = reason;
 
+        // tag::refguide[]
+        // ...
+    }
+    // end::refguide[]
 
-    // -- veto
     /**
      * Use instead of {@link #hide()}, {@link #disable(String)} and {@link #invalidate(String)}; just delegates to
      * appropriate vetoing method based upon the {@link #getEventPhase() phase}.
@@ -254,8 +281,10 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
      *
      * @see #veto(org.apache.isis.applib.services.i18n.TranslatableString)
      */
-    @Programmatic
+    // tag::refguide[]
     public void veto(final String reason, final Object... args) {
+        // end::refguide[]
+
         switch (getEventPhase()) {
         case HIDE:
             hide();
@@ -278,7 +307,12 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         default:
             throw _Exceptions.unmatchedCase(getEventPhase());
         }
+
+        // tag::refguide[]
+        // ...
     }
+
+    // end::refguide[]
     /**
      * Use instead of {@link #hide()}, {@link #disable(org.apache.isis.applib.services.i18n.TranslatableString)} and {@link #invalidate(org.apache.isis.applib.services.i18n.TranslatableString)}; just delegates to
      * appropriate vetoing method based upon the {@link #getEventPhase() phase}.
@@ -291,8 +325,10 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
      *
      * @see #veto(String, Object...)
      */
-    @Programmatic
+    // tag::refguide[]
     public void veto(final TranslatableString translatableReason) {
+        // end::refguide[]
+
         switch (getEventPhase()) {
         case HIDE:
             hide();
@@ -309,10 +345,12 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         default:
             throw _Exceptions.unmatchedCase(getEventPhase());
         }
-    }
 
+        // tag::refguide[]
+        // ...
+    }
+    // end::refguide[]
 
-    // -- userData
     /**
      * Provides a mechanism to pass data to the next {@link #getEventPhase() phase}.
      */
@@ -321,15 +359,20 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
     /**
      * Obtain user-data, as set by a previous {@link #getEventPhase() phase}.
      */
+    // tag::refguide[]
     public Object get(Object key) {
         return userData.get(key);
     }
+
+    // end::refguide[]
     /**
      * Set user-data, for the use of a subsequent {@link #getEventPhase() phase}.
      */
+    // tag::refguide[]
     public void put(Object key, Object value) {
         userData.put(key, value);
     }
+    // end::refguide[]
 
     private static final ToString<AbstractDomainEvent<?>> toString =
             ObjectContracts.<AbstractDomainEvent<?>>
@@ -343,5 +386,7 @@ public abstract class AbstractDomainEvent<S> extends EventObjectBase<S> {
         return toString.toString(this);
     }
 
+    // tag::refguide[]
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/ActionDomainEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/ActionDomainEvent.java
index 9c66001..b935e91 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/ActionDomainEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/ActionDomainEvent.java
@@ -24,37 +24,38 @@ import org.apache.isis.applib.annotation.SemanticsOf;
 import org.apache.isis.applib.util.ObjectContracts;
 import org.apache.isis.applib.util.ToString;
 
+import lombok.Getter;
+
+// tag::refguide[]
 public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
 
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.Action#domainEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.action.domain-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ActionDomainEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ActionDomainEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ActionDomainEvent<Object> {}
 
-
-
+    // end::refguide[]
     /**
      * If used then the framework will set state via (non-API) setters.
      *
@@ -87,95 +88,34 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
     //    }
 
 
-    // -- actionSemantics
-    public SemanticsOf getSemantics() {
-        return actionSemantics;
-    }
-
-    private SemanticsOf actionSemantics;
+    // tag::refguide[]
+    @Getter
+    private SemanticsOf semantics;
 
-    /**
-     * @deprecated - use {@link #getSemantics()} instead.
-     */
-    @Deprecated
-    public SemanticsOf getActionSemantics() {
-        return actionSemantics;
-    }
-
-    /**
-     * Not API - set by the framework.
-     */
-    public void setActionSemantics(SemanticsOf actionSemantics) {
-        this.actionSemantics = actionSemantics;
-    }
-
-
-
-    // -- parameterNames
+    @Getter
     private List<String> parameterNames;
-    public List<String> getParameterNames() {
-        return parameterNames;
-    }
-    public void setParameterNames(final List<String> parameterNames) {
-        this.parameterNames = parameterNames;
-    }
-
 
-    // -- parameterTypes
+    @Getter
     private List<Class<?>> parameterTypes;
-    public List<Class<?>> getParameterTypes() {
-        return parameterTypes;
-    }
-
-    public void setParameterTypes(final List<Class<?>> parameterTypes) {
-        this.parameterTypes = parameterTypes;
-    }
-
-
-
-    // region > mixedIn
-    private Object mixedIn;
 
+    // end::refguide[]
     /**
      * Populated only for mixins; holds the underlying domain object that the mixin contributes to.
      */
-    @Override
-    public Object getMixedIn() {
-        return mixedIn;
-    }
-    /**
-     * Not API - set by the framework.
-     */
-    @Override
-    public void setMixedIn(final Object mixedIn) {
-        this.mixedIn = mixedIn;
-    }
-    // endregion
+    // tag::refguide[]
+    @Getter
+    private Object mixedIn;
 
-    // -- arguments
-    private List<Object> arguments;
+    // end::refguide[]
     /**
      * The arguments being used to invoke the action; populated at {@link Phase#VALIDATE} and subsequent phases
      * (but null for {@link Phase#HIDE hidden} and {@link Phase#DISABLE disable} phases).
      */
-    public List<Object> getArguments() {
-        return arguments;
-    }
-
-    /**
-     * Not API - set by the framework.
-     */
-    public void setArguments(List<Object> arguments) {
-        this.arguments = arguments;
-    }
-
-
-    // -- returnValue
-    /**
-     *
-     */
-    private Object returnValue;
+    // tag::refguide[]
+    @Getter
+    private List<Object> arguments;
 
+    // end::refguide[]
     /**
      * The value returned by the action.
      *
@@ -184,20 +124,54 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
      *     {@link #getEventPhase() phase}.
      * </p>
      */
-    public Object getReturnValue() {
-        return returnValue;
-    }
+    // tag::refguide[]
+    @Getter
+    private Object returnValue;
 
+    // end::refguide[]
     /**
      * Set by the framework.
      *
      * Event subscribers can replace the value with some other value if they wish, though only in the
      * {@link Phase#EXECUTED} phase.
      */
+    // tag::refguide[]
     public void setReturnValue(final Object returnValue) {
         this.returnValue = returnValue;
     }
 
+    // end::refguide[]
+    /**
+     * Not API - set by the framework.
+     */
+    public void setSemantics(SemanticsOf semantics) {
+        this.semantics = semantics;
+    }
+    /**
+     * Not API - set by the framework.
+     */
+    public void setParameterNames(final List<String> parameterNames) {
+        this.parameterNames = parameterNames;
+    }
+    /**
+     * Not API - set by the framework.
+     */
+    public void setParameterTypes(final List<Class<?>> parameterTypes) {
+        this.parameterTypes = parameterTypes;
+    }
+    /**
+     * Not API - set by the framework.
+     */
+    @Override
+    public void setMixedIn(final Object mixedIn) {
+        this.mixedIn = mixedIn;
+    }
+    /**
+     * Not API - set by the framework.
+     */
+    public void setArguments(List<Object> arguments) {
+        this.arguments = arguments;
+    }
 
 
     private static final ToString<ActionDomainEvent<?>> toString = ObjectContracts.<ActionDomainEvent<?>>
@@ -211,5 +185,7 @@ public abstract class ActionDomainEvent<S> extends AbstractDomainEvent<S> {
         return toString.toString(this);
     }
 
+    // tag::refguide[]
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/CollectionDomainEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/CollectionDomainEvent.java
index fe5826a..3bf5192 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/CollectionDomainEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/CollectionDomainEvent.java
@@ -21,38 +21,38 @@ package org.apache.isis.applib.events.domain;
 import org.apache.isis.applib.util.ObjectContracts;
 import org.apache.isis.applib.util.ToString;
 
+import lombok.Getter;
+
+// tag::refguide[]
 public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S> {
 
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.Collection#domainEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.collection.domain-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends CollectionDomainEvent<Object, Object> { }
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends CollectionDomainEvent<Object, Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends CollectionDomainEvent<Object, Object> {}
 
-
-
-    // -- constructor
+    // end::refguide[]
 
     /**
      * If used then the framework will set state via (non-API) setters.
@@ -66,52 +66,54 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S>
 
 
 
-    // -- value
-    private T value;
-
     /**
      * The proposed reference to either add or remove (per {@link #getOf()}), populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE}
      * and subsequent phases (is null for {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden} and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
      */
-    public T getValue() {
-        return value;
-    }
-    /**
-     * Not API, set by the framework.
-     */
-    public void setValue(T value) {
-        this.value = value;
-    }
-
+    // tag::refguide[]
+    @Getter
+    private T value;
 
-    // -- Of
     public static enum Of {
+        // end::refguide[]
         /**
          * The collection is being accessed
          * ({@link Phase#HIDE hide} and
          * {@link Phase#DISABLE disable}) checks.
          */
+        // tag::refguide[]
         ACCESS,
+
+        // end::refguide[]
         /**
          * The collection is being added to
          * ({@link Phase#VALIDATE validity} check and
          * {@link Phase#EXECUTED execution}).
          */
+        // tag::refguide[]
         ADD_TO,
+
+        // end::refguide[]
         /**
          * The collection is being removed from
          * ({@link Phase#VALIDATE validity} check and
          * {@link Phase#EXECUTED execution}).
          */
+        // tag::refguide[]
         REMOVE_FROM
+
     }
 
+    @Getter
     private Of of;
 
-    public Of getOf() {
-        return of;
+    // end::refguide[]
+    /**
+     * Not API, set by the framework.
+     */
+    public void setValue(T value) {
+        this.value = value;
     }
-
     /**
      * Not API; updates from {@link Of#ACCESS} to either {@link Of#ADD_TO} or {@link Of#REMOVE_FROM} when hits the
      * {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE validation phase}.
@@ -121,7 +123,6 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S>
     }
 
 
-
     private static final ToString<CollectionDomainEvent<?,?>> toString =
             ObjectContracts.<CollectionDomainEvent<?,?>>
     toString("source", CollectionDomainEvent::getSource)
@@ -136,4 +137,7 @@ public abstract class CollectionDomainEvent<S,T> extends AbstractDomainEvent<S>
         return toString.toString(this);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/PropertyDomainEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/PropertyDomainEvent.java
index a8649b4..405f4a5 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/PropertyDomainEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/domain/PropertyDomainEvent.java
@@ -21,38 +21,38 @@ package org.apache.isis.applib.events.domain;
 import org.apache.isis.applib.util.ObjectContracts;
 import org.apache.isis.applib.util.ToString;
 
+import lombok.Getter;
+
+// tag::refguide[]
 public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
 
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.Property#domainEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.property.domain-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends PropertyDomainEvent<Object, Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends PropertyDomainEvent<Object, Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends PropertyDomainEvent<Object, Object> {}
 
-
-    // -- constructors
-
+    // end::refguide[]
     /**
      * If used then the framework will set state via (non-API) setters.
      *
@@ -63,17 +63,25 @@ public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
     public PropertyDomainEvent() {
     }
 
-
-    // -- oldValue
+    // end::refguide[]
+    /**
+     * The current (pre-modification) value of the property; populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
+     * (but null for {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden} and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
+     */
+    // tag::refguide[]
+    @Getter
     private T oldValue;
 
+    // end::refguide[]
     /**
-     * The current (pre-modification) value of the property; populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
+     * The proposed (post-modification) value of the property; populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
      * (but null for {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden} and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
      */
-    public T getOldValue() {
-        return oldValue;
-    }
+    // tag::refguide[]
+    @Getter
+    private T newValue;
+
+    // end::refguide[]
     /**
      * Not API; for framework use only.
      */
@@ -81,16 +89,6 @@ public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
         this.oldValue = oldValue;
     }
 
-
-    // -- newValue
-    private T newValue;
-    /**
-     * The proposed (post-modification) value of the property; populated at {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#VALIDATE} and subsequent phases
-     * (but null for {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#HIDE hidden} and {@link org.apache.isis.applib.events.domain.AbstractDomainEvent.Phase#DISABLE disable} phases).
-     */
-    public T getNewValue() {
-        return newValue;
-    }
     /**
      * Not API; for framework use only.
      */
@@ -113,4 +111,7 @@ public abstract class PropertyDomainEvent<S,T> extends AbstractDomainEvent<S> {
         return toString.toString(this);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/AbstractLifecycleEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/AbstractLifecycleEvent.java
index 2915043..33be455 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/AbstractLifecycleEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/AbstractLifecycleEvent.java
@@ -18,8 +18,9 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
-import org.apache.isis.applib.events.domain.EventObjectBase;
+import org.apache.isis.applib.events.EventObjectBase;
 
+// tag::refguide[]
 public abstract class AbstractLifecycleEvent<S> extends EventObjectBase<S> {
 
     public AbstractLifecycleEvent() {
@@ -30,4 +31,5 @@ public abstract class AbstractLifecycleEvent<S> extends EventObjectBase<S> {
         super(source);
     }
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectCreatedEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectCreatedEvent.java
index 061d5c1..1a2482e 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectCreatedEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectCreatedEvent.java
@@ -18,41 +18,44 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectCreatedEvent<S> extends AbstractLifecycleEvent<S> {
 
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#createdLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.created-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ObjectCreatedEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ObjectCreatedEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ObjectCreatedEvent<Object> {}
 
-
+    // end::refguide[]
     public ObjectCreatedEvent() {
     }
-    
+
     public ObjectCreatedEvent(final S source) {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectLoadedEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectLoadedEvent.java
index e1713c7..acc5780 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectLoadedEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectLoadedEvent.java
@@ -18,43 +18,44 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectLoadedEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#loadedLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.loaded-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ObjectLoadedEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ObjectLoadedEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ObjectLoadedEvent<Object> {}
 
-
+    // end::refguide[]
     public ObjectLoadedEvent() {
     }
-    
+
     public ObjectLoadedEvent(final S source) {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectPersistedEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectPersistedEvent.java
index 019f82b..cf364b6 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectPersistedEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectPersistedEvent.java
@@ -18,43 +18,45 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectPersistedEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#persistedLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.persisted-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+     // tag::refguide[]
     public static class Default extends ObjectPersistedEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+     // tag::refguide[]
     public static class Noop extends ObjectPersistedEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+     // tag::refguide[]
     public static class Doop extends ObjectPersistedEvent<Object> {}
 
+    // end::refguide[]
 
     public ObjectPersistedEvent() {
     }
-    
+
     public ObjectPersistedEvent(final S source) {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectPersistingEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectPersistingEvent.java
index 27527f7..6f5c070 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectPersistingEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectPersistingEvent.java
@@ -18,37 +18,36 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectPersistingEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#persistingLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.persisting-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+     // tag::refguide[]
     public static class Default extends ObjectPersistingEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+     // tag::refguide[]
     public static class Noop extends ObjectPersistingEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+     // tag::refguide[]
     public static class Doop extends ObjectPersistingEvent<Object> {}
 
+    // end::refguide[]
 
     public ObjectPersistingEvent() {
     }
@@ -56,4 +55,7 @@ public abstract class ObjectPersistingEvent<S> extends AbstractLifecycleEvent<S>
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectRemovingEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectRemovingEvent.java
index eb606cf..6ad99af 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectRemovingEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectRemovingEvent.java
@@ -18,37 +18,36 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectRemovingEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#removingLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.removing-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ObjectRemovingEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ObjectRemovingEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ObjectRemovingEvent<Object> {}
 
+    // end::refguide[]
 
     public ObjectRemovingEvent() {
     }
@@ -57,4 +56,7 @@ public abstract class ObjectRemovingEvent<S> extends AbstractLifecycleEvent<S> {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectUpdatedEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectUpdatedEvent.java
index 4cf4a48..4e2f080 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectUpdatedEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectUpdatedEvent.java
@@ -18,37 +18,36 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectUpdatedEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#updatedLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.updated-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ObjectUpdatedEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ObjectUpdatedEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ObjectUpdatedEvent<Object> {}
 
+    // end::refguide[]
 
     public ObjectUpdatedEvent() {
     }
@@ -57,4 +56,7 @@ public abstract class ObjectUpdatedEvent<S> extends AbstractLifecycleEvent<S> {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectUpdatingEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectUpdatingEvent.java
index 8258ff9..c0a4813 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectUpdatingEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/lifecycle/ObjectUpdatingEvent.java
@@ -18,37 +18,36 @@
  */
 package org.apache.isis.applib.events.lifecycle;
 
+// tag::refguide[]
 public abstract class ObjectUpdatingEvent<S> extends AbstractLifecycleEvent<S> {
 
-    
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObject#updatingLifecycleEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object.updating-lifecycle-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends ObjectUpdatingEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends ObjectUpdatingEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends ObjectUpdatingEvent<Object> {}
 
+    // end::refguide[]
 
     public ObjectUpdatingEvent() {
     }
@@ -57,4 +56,7 @@ public abstract class ObjectUpdatingEvent<S> extends AbstractLifecycleEvent<S> {
         super(source);
     }
 
-}
\ No newline at end of file
+    // tag::refguide[]
+
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/AbstractUiEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/AbstractUiEvent.java
index 72df250..b57be4a 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/AbstractUiEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/AbstractUiEvent.java
@@ -21,11 +21,12 @@ package org.apache.isis.applib.events.ui;
 import java.util.HashMap;
 import java.util.Map;
 
-import org.apache.isis.applib.events.domain.EventObjectBase;
+import org.apache.isis.applib.events.EventObjectBase;
 
+// tag::refguide[]
 public abstract class AbstractUiEvent<S> extends EventObjectBase<S> {
 
-    // -- constructors
+    // end::refguide[]
     /**
      * If used then the framework will set state via (non-API) setters.
      *
@@ -38,7 +39,6 @@ public abstract class AbstractUiEvent<S> extends EventObjectBase<S> {
         super(source);
     }
 
-    // -- userData
     /**
      * Provides a mechanism to pass data around.
      */
@@ -47,14 +47,17 @@ public abstract class AbstractUiEvent<S> extends EventObjectBase<S> {
     /**
      * Obtain user-data, as set by any other subscribers.
      */
+    // tag::refguide[]
     public Object get(Object key) {
         return userData.get(key);
     }
     /**
      * Set user-data, for the use of other subscribers.
      */
+    // tag::refguide[]
     public void put(Object key, Object value) {
         userData.put(key, value);
     }
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/CssClassUiEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/CssClassUiEvent.java
index 7a10d94..a3ea0bf 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/CssClassUiEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/CssClassUiEvent.java
@@ -20,68 +20,70 @@ package org.apache.isis.applib.events.ui;
 
 import org.apache.isis.applib.annotation.DomainObjectLayout;
 
+import lombok.Getter;
+import lombok.Setter;
+
 /**
  * Emitted for subscribers to obtain a cssClass hint (equivalent to the <tt>cssClass()</tt> supporting method or the {@link DomainObjectLayout#cssClass()} attribute).
  */
+// tag::refguide[]
 public abstract class CssClassUiEvent<S> extends AbstractUiEvent<S> {
 
-    // -- constructors
-    /**
-     * If used then the framework will set state via (non-API) setters.
-     *
-     */
-    public CssClassUiEvent() {
-        this(null);
-    }
-
-    public CssClassUiEvent(final S source) {
-        super(source);
-    }
-
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObjectLayout#cssClassUiEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object-layout.css-class-ui-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends CssClassUiEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends CssClassUiEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends CssClassUiEvent<Object> {}
 
+    // end::refguide[]
 
-    // -- cssClass
-    private String cssClass;
+    /**
+     * If used then the framework will set state via (non-API) setters.
+     *
+     */
+    public CssClassUiEvent() {
+        this(null);
+    }
+
+    public CssClassUiEvent(final S source) {
+        super(source);
+    }
 
     /**
      * The CSS class as provided by a subscriber using {@link #setCssClass(String)}.
      */
-    public String getCssClass() {
-        return cssClass;
-    }
+    // tag::refguide[]
+    @Getter
+    private String cssClass;
 
+    // end::refguide[]
     /**
      * For subscribers to call to provide a CSS class for this object.
      */
+    // tag::refguide[]
     public void setCssClass(final String cssClass) {
         this.cssClass = cssClass;
     }
 
-
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/LayoutUiEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/LayoutUiEvent.java
index b267f5a..5804488 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/LayoutUiEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/LayoutUiEvent.java
@@ -22,71 +22,69 @@ import java.util.EventObject;
 
 import org.apache.isis.applib.annotation.DomainObjectLayout;
 
+import lombok.Getter;
+
 /**
  * Emitted for subscribers to obtain a layout hint (equivalent to the <tt>layout()</tt> supporting method).
  */
+// tag::refguide[]
 public abstract class LayoutUiEvent<S> extends AbstractUiEvent<S> {
 
-    //region > constructors
-    /**
-     * If used then the framework will set state via (non-API) setters.
-     *
-     * <p>
-     *     Because the {@link EventObject} superclass prohibits a null source, a dummy value is temporarily used.
-     * </p>
-     */
-    public LayoutUiEvent() {
-        this(null);
-    }
-
-    public LayoutUiEvent(final S source) {
-        super(source);
-    }
-
-    //endregion
-
-    //region > Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link DomainObjectLayout#layoutUiEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object-layout.layout-ui-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends LayoutUiEvent<Object> { }
-    //endregion
-
-    //region > Noop class
 
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends LayoutUiEvent<Object> { }
-    //endregion
-
-    //region > Doop class
 
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends LayoutUiEvent<Object> { }
-    //endregion
 
-    //region > layout
-    private String layout;
+    // end::refguide[]
+    /**
+     * If used then the framework will set state via (non-API) setters.
+     *
+     * <p>
+     *     Because the {@link EventObject} superclass prohibits a null source, a dummy value is temporarily used.
+     * </p>
+     */
+    public LayoutUiEvent() {
+        this(null);
+    }
+
+    public LayoutUiEvent(final S source) {
+        super(source);
+    }
 
     /**
      * The name of the alternate layout to use, as provided by a subscriber using {@link #setLayout(String)}.
      */
-    public String getLayout() {
-        return layout;
-    }
+    // tag::refguide[]
+    @Getter
+    private String layout;
 
+    // end::refguide[]
     /**
      * For subscribers to call to provide a layout for this object.
      */
+    // tag::refguide[]
     public void setLayout(final String layout) { }
-    //endregion
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/TitleUiEvent.java b/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/TitleUiEvent.java
index 617be2b..88e6829 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/TitleUiEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/events/ui/TitleUiEvent.java
@@ -22,40 +22,42 @@ import java.util.EventObject;
 
 import org.apache.isis.applib.services.i18n.TranslatableString;
 
+import lombok.Getter;
+
 /**
  * Emitted for subscribers to obtain a cssClass hint (equivalent to the <tt>title()</tt> supporting method).
  */
+// tag::refguide[]
 public abstract class TitleUiEvent<S> extends AbstractUiEvent<S> {
 
-    // -- Default class
+    // end::refguide[]
     /**
      * This class is the default for the
      * {@link org.apache.isis.applib.annotation.DomainObjectLayout#titleUiEvent()} annotation attribute.  Whether this
      * raises an event or not depends upon the <tt>isis.core.meta-model.annotation.domain-object-layout.title-ui-event.post-for-default</tt>
      * configuration property.
      */
+    // tag::refguide[]
     public static class Default extends TitleUiEvent<Object> {}
 
-
-    // -- Noop class
-
+    // end::refguide[]
     /**
      * Convenience class to use indicating that an event should <i>not</i> be posted (irrespective of the configuration
      * property seting for the {@link Default} event.
      */
+    // tag::refguide[]
     public static class Noop extends TitleUiEvent<Object> {}
 
-
-    // -- Doop class
-
+    // end::refguide[]
     /**
      * Convenience class meaning that an event <i>should</i> be posted (irrespective of the configuration
      * property setting for the {@link Default} event..
      */
+    // tag::refguide[]
     public static class Doop extends TitleUiEvent<Object> {}
 
+    // end::refguide[]
 
-    // -- constructors
     /**
      * If used then the framework will set state via (non-API) setters.
      *
@@ -72,10 +74,6 @@ public abstract class TitleUiEvent<S> extends AbstractUiEvent<S> {
     }
 
 
-
-    // -- title
-    private String title;
-
     /**
      * The title as provided by a subscriber using {@link #setTitle(String)}.
      *
@@ -83,21 +81,21 @@ public abstract class TitleUiEvent<S> extends AbstractUiEvent<S> {
      *     Note that a {@link #getTranslatableTitle()} will be used in preference, if available.
      * </p>
      */
-    public String getTitle() {
-        return title;
-    }
+    // tag::refguide[]
+    @Getter
+    private String title;
 
+    // end::refguide[]
     /**
      * For subscribers to call to provide a (non-translated) title for this object.
      */
+    // tag::refguide[]
     public void setTitle(final String title) {
         this.title = title;
     }
 
 
-    // -- translatableTitle
-    private TranslatableString translatableTitle;
-
+    // end::refguide[]
     /**
      * The translatable (i18n) title as provided by a subscriber using {@link #setTranslatableTitle(TranslatableString)}.
      *
@@ -106,16 +104,19 @@ public abstract class TitleUiEvent<S> extends AbstractUiEvent<S> {
      *     {@link #getTitle() non-translatable title}.
      * </p>
      */
-    public TranslatableString getTranslatableTitle() {
-        return translatableTitle;
-    }
+    // tag::refguide[]
+    @Getter
+    private TranslatableString translatableTitle;
 
     /**
      * For subscribers to call to provide a translatable (i18n) title for this object.
      */
+    // tag::refguide[]
     public void setTranslatableTitle(final TranslatableString translatableTitle) {
         this.translatableTitle = translatableTitle;
     }
 
+    // tag::refguide[]
 
-}
\ No newline at end of file
+}
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/graph/Edge.java b/api/applib/src/main/adoc/modules/applib-cm/examples/graph/Edge.java
index 1650f5b..bd4c0f3 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/graph/Edge.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/graph/Edge.java
@@ -25,9 +25,12 @@ package org.apache.isis.applib.graph;
  *
  * @param <T> type constraint for values contained by this edge's vertices
  */
+// tag::refguide[]
 public interface Edge<T> {
 
-    public Vertex<T> getFrom();
-    public Vertex<T> getTo();
+    Vertex<T> getFrom();
+
+    Vertex<T> getTo();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/graph/SimpleEdge.java b/api/applib/src/main/adoc/modules/applib-cm/examples/graph/SimpleEdge.java
index 3eba78a..3ba7003 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/graph/SimpleEdge.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/graph/SimpleEdge.java
@@ -27,6 +27,7 @@ import lombok.Value;
  *
  * @param <T> type constraint for values contained by this edge's vertices
  */
+// tag::refguide[]
 @Value(staticConstructor = "of")
 public class SimpleEdge<T> implements Edge<T> {
 
@@ -34,3 +35,4 @@ public class SimpleEdge<T> implements Edge<T> {
     Vertex<T> to;
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/graph/Vertex.java b/api/applib/src/main/adoc/modules/applib-cm/examples/graph/Vertex.java
index d2d09b0..58694f7 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/graph/Vertex.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/graph/Vertex.java
@@ -27,19 +27,16 @@ import java.util.stream.Stream;
  *
  * @param <T> type constraint for values contained by this vertex
  */
+// tag::refguide[]
 public interface Vertex<T> {
 
-    // -- VALUE
-
     public T getValue();
 
-    // -- EDGES
-
-    public int getIncomingCount();
-    public int getOutgoingCount();
-
-    public Stream<Edge<T>> streamIncoming();
-    public Stream<Edge<T>> streamOutgoing();
+    int getIncomingCount();
+    int getOutgoingCount();
 
+    Stream<Edge<T>> streamIncoming();
+    Stream<Edge<T>> streamOutgoing();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/security/RoleMemento.java b/api/applib/src/main/adoc/modules/applib-cm/examples/security/RoleMemento.java
index f9802fd..a220a2b 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/security/RoleMemento.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/security/RoleMemento.java
@@ -21,8 +21,12 @@ package org.apache.isis.applib.security;
 
 import org.apache.isis.applib.annotation.MemberOrder;
 
+import lombok.Getter;
+
+// tag::refguide[]
 public final class RoleMemento {
 
+    // end::refguide[]
     /**
      * Creates a new role with the specified name. Description is left blank.
      */
@@ -44,29 +48,18 @@ public final class RoleMemento {
         this.description = description;
     }
 
-    // {{ Identification
+    // tag::refguide[]
     public String title() {
         return name;
     }
 
-    // }}
-
-    // {{ Name
-    private final String name;
-
     @MemberOrder(sequence = "1.1")
-    public String getName() {
-        return name;
-    }
-
-    // }}
+    @Getter
+    private final String name;
 
-    // {{ Description
+    @MemberOrder(sequence = "1.2")
+    @Getter
     private final String description;
 
-    @MemberOrder(sequence = "1.2")
-    public String getDescription() {
-        return description;
-    }
-    // }}
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/security/UserMemento.java b/api/applib/src/main/adoc/modules/applib-cm/examples/security/UserMemento.java
index 7b26047..bf3bb7a 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/security/UserMemento.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/security/UserMemento.java
@@ -25,13 +25,17 @@ import java.util.List;
 
 import org.apache.isis.applib.annotation.MemberOrder;
 
+import lombok.Getter;
+import lombok.experimental.UtilityClass;
+
 /**
  * Details, obtained from the container, about the user and his roles.
  * Read-only.
  */
+// tag::refguide[]
 public final class UserMemento {
 
-    // -- constructors
+    // end::refguide[]
     /**
      * Creates a new user with the specified name and no roles.
      */
@@ -57,44 +61,30 @@ public final class UserMemento {
         this.roles.addAll(roles);
     }
 
-
-    // -- title
+    // tag::refguide[]
     public String title() {
         return name;
     }
 
-
-
-    // -- name, NameType
-
-    // {{ (User) Name, isCurrentUser
-    private final String name;
-
+    // end::refguide[]
     /**
      * The user's login name.
      */
+    // tag::refguide[]
     @MemberOrder(sequence = "1.1")
-    public String getName() {
-        return name;
-    }
-
-    public static class NameType {
-
-        private NameType() {}
-
-        public static class Meta {
-
-            public static final int MAX_LEN = 50;
-
-            private Meta() {}
-
-        }
-
-    }
-
+    @Getter
+    private final String name;
 
+    // end::refguide[]
+    /**
+     * The roles associated with this user.
+     */
+    // tag::refguide[]
+    @Getter
+    @MemberOrder(sequence = "1.1")
+    private final List<RoleMemento> roles = new ArrayList<RoleMemento>();
 
-    // -- isCurrentUser
+    // end::refguide[]
     /**
      * Determine if the specified name is this user.
      *
@@ -109,19 +99,6 @@ public final class UserMemento {
         return name.equals(userName);
     }
 
-
-
-    // -- roles
-    private final List<RoleMemento> roles = new ArrayList<RoleMemento>();
-
-    /**
-     * The roles associated with this user.
-     */
-    @MemberOrder(sequence = "1.1")
-    public List<RoleMemento> getRoles() {
-        return roles;
-    }
-
     /**
      * Determines if the user fulfills the specified role.
      *
@@ -144,9 +121,6 @@ public final class UserMemento {
         return false;
     }
 
-
-
-    // -- toString
     @Override
     public String toString() {
         final StringBuilder buf = new StringBuilder();
@@ -156,6 +130,15 @@ public final class UserMemento {
         return "User [name=" + getName() + ",roles=" + buf.toString() + "]";
     }
 
+    @UtilityClass
+    public static class NameType {
+        @UtilityClass
+        public static class Meta {
+            public static final int MAX_LEN = 50;
+        }
+    }
 
+    // tag::refguide[]
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/AbstractSpecification2.java b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/AbstractSpecification2.java
index 7bd193f..2036587 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/AbstractSpecification2.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/AbstractSpecification2.java
@@ -40,6 +40,8 @@ import org.apache.isis.core.commons.internal.base._Casts;
  * Implementation note: inspired by (borrowed code from) Hamcrest's
  * <tt>TypeSafeMatcher</tt>.
  */
+// tag::refguide[]
+// end::refguide[]
 public abstract class AbstractSpecification2<T> implements Specification2 {
 
     public enum TypeChecking {
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/Specification.java b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/Specification.java
index d52c2c2..f08d788 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/Specification.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/Specification.java
@@ -23,11 +23,16 @@ package org.apache.isis.applib.spec;
  * An implementation of the <i>Specification</i> pattern, as described in Eric
  * Evans' <i>Domain Driven Design</i>, p224.
  */
+// tag::refguide[]
 public interface Specification {
 
+    // end::refguide[]
     /**
      * If <tt>null</tt> then satisfied, otherwise is reason why the
      * specification is not satisfied.
      */
-    public String satisfies(Object obj);
+    // tag::refguide[]
+    String satisfies(Object obj);
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/Specification2.java b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/Specification2.java
index c4d8233..6b391b1 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/Specification2.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/Specification2.java
@@ -29,10 +29,15 @@ import org.apache.isis.applib.services.i18n.TranslatableString;
  *     it will never be called by the framework.
  * </p>
  */
+// tag::refguide[]
 public interface Specification2 extends Specification {
 
+    // end::refguide[]
     /**
      * If <tt>null</tt> then satisfied, otherwise is the reason (as a {@link TranslatableString} translatable string) as to why the specification is not satisfied.
      */
-    public TranslatableString satisfiesTranslatable(Object obj);
+    // tag::refguide[]
+    TranslatableString satisfiesTranslatable(Object obj);
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationAnd.java b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationAnd.java
index df97725..d66e00f 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationAnd.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationAnd.java
@@ -43,6 +43,7 @@ import org.apache.isis.applib.util.ReasonBuffer;
  * @see SpecificationOr
  * @see SpecificationNot
  */
+// tag::refguide[]
 public abstract class SpecificationAnd implements Specification {
 
     private final Specification[] specifications;
@@ -62,3 +63,4 @@ public abstract class SpecificationAnd implements Specification {
     }
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationNot.java b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationNot.java
index a8af79f..64ffffa 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationNot.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationNot.java
@@ -44,6 +44,7 @@ package org.apache.isis.applib.spec;
  * @see SpecificationAnd
  * @see SpecificationOr
  */
+// tag::refguide[]
 public abstract class SpecificationNot implements Specification {
 
     private final Specification specification;
@@ -58,3 +59,4 @@ public abstract class SpecificationNot implements Specification {
         return satisfies != null ? null : "not satisfied";
     }
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationOr.java b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationOr.java
index 1e14584..62029f5 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationOr.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/spec/SpecificationOr.java
@@ -43,6 +43,7 @@ import org.apache.isis.applib.util.ReasonBuffer;
  * @see SpecificationAnd
  * @see SpecificationNot
  */
+// tag::refguide[]
 public abstract class SpecificationOr implements Specification {
 
     private final Specification[] specifications;
@@ -62,7 +63,8 @@ public abstract class SpecificationOr implements Specification {
             }
             buf.append(reasonNotSatisfiedIfAny);
         }
-        return buf.getReason(); // may be null if all were satisfied.
+        return buf.getReason(); // will be non-null if none were satisfied.
     }
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/util/Enums.java b/api/applib/src/main/adoc/modules/applib-cm/examples/util/Enums.java
index d2d3129..9f342ba 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/util/Enums.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/util/Enums.java
@@ -23,9 +23,10 @@ import java.util.stream.Collectors;
 
 import org.apache.isis.core.commons.internal.base._Strings;
 
-public final class Enums {
+import lombok.experimental.UtilityClass;
 
-    private Enums(){}
+@UtilityClass
+public final class Enums {
 
     public static String getFriendlyNameOf(Enum<?> anEnum) {
         return getFriendlyNameOf(anEnum.name());
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/util/JaxbUtil.java b/api/applib/src/main/adoc/modules/applib-cm/examples/util/JaxbUtil.java
index ae8f8a1..f2919f0 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/util/JaxbUtil.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/util/JaxbUtil.java
@@ -35,6 +35,7 @@ import org.apache.isis.core.commons.internal.collections._Maps;
 import org.apache.isis.core.commons.internal.resources._Resources;
 
 import lombok.val;
+import lombok.experimental.UtilityClass;
 
 
 /**
@@ -46,10 +47,9 @@ import lombok.val;
  * (non-ASF)
  * </p>
  */
+@UtilityClass
 public class JaxbUtil {
 
-    private JaxbUtil(){}
-
     // -- READ
 
     public static <T> T fromXml(
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/value/Blob.java b/api/applib/src/main/adoc/modules/applib-cm/examples/value/Blob.java
index 4a6956c..028aa33 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/value/Blob.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/value/Blob.java
@@ -30,6 +30,8 @@ import org.apache.isis.core.commons.internal.base._Strings;
 
 import lombok.val;
 
+// tag::refguide[]
+// end::refguide[]
 public final class Blob implements NamedWithMimeType {
 
     /**
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/value/Clob.java b/api/applib/src/main/adoc/modules/applib-cm/examples/value/Clob.java
index f7311a4..e1baa9d 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/value/Clob.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/value/Clob.java
@@ -29,6 +29,8 @@ import org.apache.isis.core.commons.internal.base._Strings;
 
 import lombok.val;
 
+// tag::refguide[]
+// end::refguide[]
 public final class Clob implements NamedWithMimeType {
 
     private static final long serialVersionUID = 8694189924062378527L;
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/value/Image.java b/api/applib/src/main/adoc/modules/applib-cm/examples/value/Image.java
index e282895..63df43c 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/value/Image.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/value/Image.java
@@ -26,6 +26,8 @@ import org.apache.isis.applib.annotation.Value;
 /**
  * Represents an image.
  */
+// tag::refguide[]
+// end::refguide[]
 @Value(semanticsProviderName = "org.apache.isis.core.metamodel.facets.value.image.ImageValueSemanticsProvider")
 public class Image implements Serializable {
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/value/LocalResourcePath.java b/api/applib/src/main/adoc/modules/applib-cm/examples/value/LocalResourcePath.java
index 915bc2b..a0eb7c6 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/value/LocalResourcePath.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/value/LocalResourcePath.java
@@ -31,6 +31,8 @@ import lombok.NonNull;
 /**
  * Represents a local resource path, typically a relative path originating at this web-app's root or context-root.
  */
+// tag::refguide[]
+// end::refguide[]
 @Value(semanticsProviderName = "org.apache.isis.core.metamodel.facets.value.localrespath.LocalResourcePathValueSemanticsProvider")
 public final class LocalResourcePath implements Serializable {
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/value/Markup.java b/api/applib/src/main/adoc/modules/applib-cm/examples/value/Markup.java
index c70d337..9b45652 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/value/Markup.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/value/Markup.java
@@ -27,6 +27,8 @@ import org.apache.isis.applib.annotation.Value;
  * Immutable value type holding pre-rendered HTML.
  *
  */
+// tag::refguide[]
+// end::refguide[]
 @Value(semanticsProviderName = "org.apache.isis.core.metamodel.facets.value.markup.MarkupValueSemanticsProvider")
 public class Markup implements Serializable {
     private static final long serialVersionUID = 1L;
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/value/NamedWithMimeType.java b/api/applib/src/main/adoc/modules/applib-cm/examples/value/NamedWithMimeType.java
index 796dc7e..19e01a7 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/value/NamedWithMimeType.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/value/NamedWithMimeType.java
@@ -28,6 +28,8 @@ import org.apache.isis.core.commons.collections.Can;
 
 import lombok.Getter;
 
+// tag::refguide[]
+// end::refguide[]
 public interface NamedWithMimeType extends Serializable {
 
     public String getName();
diff --git a/api/applib/src/main/adoc/modules/applib-cm/examples/value/Password.java b/api/applib/src/main/adoc/modules/applib-cm/examples/value/Password.java
index 01a8435..fe536dd 100644
--- a/api/applib/src/main/adoc/modules/applib-cm/examples/value/Password.java
+++ b/api/applib/src/main/adoc/modules/applib-cm/examples/value/Password.java
@@ -24,6 +24,8 @@ import java.util.Objects;
 
 import org.apache.isis.applib.annotation.Value;
 
+// tag::refguide[]
+// end::refguide[]
 @Value(semanticsProviderName = "org.apache.isis.core.metamodel.facets.value.password.PasswordValueSemanticsProvider")
 @lombok.Value
 public class Password implements Serializable {
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/HasUniqueId.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/HasUniqueId.java
index 6dc058d..57245db 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/HasUniqueId.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/HasUniqueId.java
@@ -26,11 +26,15 @@ import java.util.UUID;
  * and so can be associated together using a unique identifier.
  *
  */
+// tag::refguide[]
 public interface HasUniqueId {
 
+    // end::refguide[]
     /**
      * The unique identifier (a GUID) of the request/interaction/transaction.
      */
+    // tag::refguide[]
     UUID getUniqueId();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/HasUsername.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/HasUsername.java
index dbdf815..7f7a240 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/HasUsername.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/HasUsername.java
@@ -26,8 +26,10 @@ package org.apache.isis.applib.services;
  * Other services can then use this username as a means to contributed actions/collections to render such additional
  * information relating to the activities of the user.
  */
+// tag::refguide[]
 public interface HasUsername {
 
-    public String getUsername();
+    String getUsername();
 
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/WithTransactionScope.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/WithTransactionScope.java
index befeaa1..c066b22 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/WithTransactionScope.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/WithTransactionScope.java
@@ -25,6 +25,8 @@ package org.apache.isis.applib.services;
  *
  * TODO: We ought instead to use Spring's @TransactionScope rather than roll-our-own.
  */
+// tag::refguide[]
 public interface WithTransactionScope {
     void resetForNextTransaction();
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metrics/MetricsService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metrics/MetricsService.java
index 103621b..633610f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/metrics/MetricsService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/metrics/MetricsService.java
@@ -24,6 +24,7 @@ import org.apache.isis.schema.ixn.v2.MemberExecutionDto;
 // tag::refguide[]
 public interface MetricsService {
 
+    // end::refguide[]
     /**
      * The number of objects that have, so far in this request, been loaded from the database.
      *
@@ -35,8 +36,10 @@ public interface MetricsService {
      *     Is captured within {@link MemberExecutionDto#getMetrics()} (accessible from {@link InteractionContext#getInteraction()}).
      * </p>
      */
+    // tag::refguide[]
     int numberObjectsLoaded();
 
+    // end::refguide[]
     /**
      * The number of objects that have, so far in this request, been dirtied/will need updating in the database); a
      * good measure of the footprint of the interaction.
@@ -49,6 +52,7 @@ public interface MetricsService {
      *     Is captured within {@link MemberExecutionDto#getMetrics()} (accessible from {@link InteractionContext#getInteraction()}).
      * </p>
      */
+    // tag::refguide[]
     int numberObjectsDirtied();
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/publish/PublishedObjects.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/publish/PublishedObjects.java
index c97656b..ebc2fcd 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/publish/PublishedObjects.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/publish/PublishedObjects.java
@@ -33,11 +33,8 @@ public interface PublishedObjects extends HasUniqueId, HasUsername {
     ChangesDto getDto();
 
     int getNumberLoaded();
-
     int getNumberCreated();
-
     int getNumberUpdated();
-
     int getNumberDeleted();
 
     int getNumberPropertiesModified();
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/publish/PublisherService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/publish/PublisherService.java
index 6e7f798..dea94e0 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/publish/PublisherService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/publish/PublisherService.java
@@ -29,11 +29,13 @@ import org.apache.isis.applib.util.schema.InteractionDtoUtils;
 // tag::refguide[]
 public interface PublisherService {
 
+    // end::refguide[]
     /**
      * Most implementations are expected to use {@link Interaction.Execution#getDto()} to create a serializable
      * XML representation of the execution.  The easiest way to do this is using {@link InteractionDtoUtils#newInteractionDto(Interaction.Execution)}.  There is
      * some flexibility here, though.
      */
+    // tag::refguide[]
     void publish(final Interaction.Execution<?, ?> execution);
 
     void publish(final PublishedObjects publishedObjects);
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/queryresultscache/QueryResultsCache.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/queryresultscache/QueryResultsCache.java
index 323869b..6b815b5 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/queryresultscache/QueryResultsCache.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/queryresultscache/QueryResultsCache.java
@@ -66,8 +66,8 @@ public interface QueryResultsCache {
     
     void resetForNextTransaction();
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     class Key {
 
         @Getter
@@ -77,6 +77,7 @@ public interface QueryResultsCache {
         @Getter
         private final Object[] keys;
 
+        // end::refguide-1[]
         public Key(Class<?> callingClass, String methodName, Object... keys) {
             this.callingClass = callingClass;
             this.methodName = methodName;
@@ -129,16 +130,17 @@ public interface QueryResultsCache {
         public String toString() {
             return callingClass.getName() + "#" + methodName  + Arrays.toString(keys);
         }
+        // tag::refguide-1[]
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide-2[]
+    // tag::refguide-2[]
     @Data
     class Value<T> {
         private final T result;
     }
-// end::refguide-2[]
+    // end::refguide-2[]
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/registry/ServiceRegistry.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/registry/ServiceRegistry.java
index ca8fbff..45972aa 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/registry/ServiceRegistry.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/registry/ServiceRegistry.java
@@ -52,6 +52,7 @@ public interface ServiceRegistry {
      * @param qualifiers
      * @return non-null
      */
+    // tag::refguide[]
     <T> Can<T> select(Class<T> type, Annotation[] qualifiers);
 
     /**
@@ -60,36 +61,54 @@ public interface ServiceRegistry {
      * @param type
      * @return non-null
      */
+    // tag::refguide[]
     default <T> Can<T> select(final Class<T> type){
+        // end::refguide[]
+
         return select(type, _Constants.emptyAnnotations);
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * Streams all registered bean adapters implementing the requested type.
      */
+    // tag::refguide[]
     default Stream<ManagedBeanAdapter> streamRegisteredBeansOfType(Class<?> requiredType) {
+        // end::refguide[]
+
         return streamRegisteredBeans()
                 .filter(beanAdapter->beanAdapter.isCandidateFor(requiredType));
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * Returns all bean adapters that have been registered.
      */
+    // tag::refguide[]
     Stream<ManagedBeanAdapter> streamRegisteredBeans();
 
+    // end::refguide[]
     /**
      * Returns a registered bean of given {@code name}.
      *
      * @param id - corresponds to the ObjectSpecificationId of the bean's type
      */
+    // tag::refguide[]
     Optional<ManagedBeanAdapter> lookupRegisteredBeanById(String id);
 
-
+    // end::refguide[]
     /**
      * Returns a registered bean of given {@code name}, or throws when no such bean.
      *
      * @param id - corresponds to the ObjectSpecificationId of the bean's type
      */
+    // tag::refguide[]
     default ManagedBeanAdapter lookupRegisteredBeanByIdElseFail(String id) {
         return lookupRegisteredBeanById(id).orElseThrow(
                 ()->_Exceptions.unrecoverable(
@@ -98,14 +117,17 @@ public interface ServiceRegistry {
 
     Optional<?> lookupBeanById(final String id);
 
+    // end::refguide[]
     /**
      * Returns a domain service implementing the requested type.
      * <p>
      * If this lookup is ambiguous, the service annotated with highest priority is returned.
      * see {@link Priority}
      */
+    // tag::refguide[]
     default <T> Optional<T> lookupService(final Class<T> serviceClass) {
-// end::refguide[]
+        // end::refguide[]
+
         val bin = select(serviceClass);
         if(bin.isEmpty()) {
             return Optional.empty();
@@ -123,20 +145,25 @@ public interface ServiceRegistry {
         bin.forEach(toMaxPrioReduction);
 
         return toMaxPrioReduction.getResult();
-// tag::refguide[]
+
+        // tag::refguide[]
         // ...
     }
 
     default <T> T lookupServiceElseFail(final Class<T> serviceClass) {
+        // end::refguide[]
+
         return lookupService(serviceClass)
                 .orElseThrow(()->
                 new NoSuchElementException("Could not locate service of type '" + serviceClass + "'"));
+
+        // tag::refguide[]
+        // ...
     }
+    // end::refguide[]
 
     // -- PRIORITY ANNOTATION HANDLING
 
-// end::refguide[]
-// tag::refguide-1[]
     class InstanceByPriorityComparator implements Comparator<Object> {
 
         private static final InstanceByPriorityComparator INSTANCE =
@@ -172,8 +199,7 @@ public interface ServiceRegistry {
         }
 
     }
-// end::refguide-1[]
 
-// tag::refguide[]
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/repository/EntityState.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/repository/EntityState.java
index c48a974..26ed267 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/repository/EntityState.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/repository/EntityState.java
@@ -31,25 +31,23 @@ public enum EntityState {
     not_Persistable,
     persistable_Attached,
     persistable_Detached,
-    persistable_Destroyed
-
+    persistable_Destroyed,
+    // end::refguide[]
     ;
 
     public boolean isPersistable() {
         return this != not_Persistable;
     }
-
     public boolean isAttached() {
         return this == persistable_Attached;
     }
-
     public boolean isDetached() {
         return this == persistable_Detached;
     }
-
     public boolean isDestroyed() {
         return this == persistable_Destroyed;
     }
 
+    // tag::refguide[]
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/repository/RepositoryService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/repository/RepositoryService.java
index ba39a0a..237b417 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/repository/RepositoryService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/repository/RepositoryService.java
@@ -32,55 +32,70 @@ import lombok.val;
 // tag::refguide[]
 public interface RepositoryService {
 
+    // end::refguide[]
     /**
      * Returns the EntityState of given {@code object}. Returns {@link EntityState#not_Persistable} for {@code object==null}.
      * @param object
      * @return (non-null)
      * @since 2.0
      */
+    // tag::refguide[]
     EntityState getEntityState(@Nullable Object object);
 
+    // end::refguide[]
     /**
      * Same as {@link org.apache.isis.applib.services.factory.FactoryService#detachedEntity(Class)}; provided as a
      * convenience because instantiating and {@link #persist(Object) persisting} are often done together.
      * @since 2.0
      */
+    // tag::refguide[]
     <T> T detachedEntity(Class<T> ofType);
 
+    // end::refguide[]
     /**
      * Persist the specified object (or do nothing if already persistent).
      *
      * @see #isPersistent(Object)
      */
+    // tag::refguide[]
     <T> T persist(T domainObject);
 
+    // end::refguide[]
     /**
      * Persist the specified object (or do nothing if already persistent) and flushes changes to the database.
      *
      * @see #persist(Object)
      */
+    // tag::refguide[]
     <T> T persistAndFlush(T domainObject);
 
+    // end::refguide[]
     /**
      * Deletes the domain object but only if is attached.
      *
      * @param domainObject
      */
+    // tag::refguide[]
     void remove(Object domainObject);
 
+    // end::refguide[]
     /**
      * Deletes the domain object but only if is persistent, and flushes changes to the database.
      *
      * @param domainObject
      */
+    // tag::refguide[]
     void removeAndFlush(Object domainObject);
 
+    // end::refguide[]
     /**
      * As {@link #allInstances(Class, long, long)}, but but returning all instances rather than just those
      *      * within the specified range..
      */
+    // tag::refguide[]
     <T> List<T> allInstances(Class<T> ofType);
 
+    // end::refguide[]
     /**
      * Returns all the instances of the specified type (including subtypes).
      * If the optional range parameters are used, the dataset returned starts
@@ -105,14 +120,18 @@ public interface RepositoryService {
      * @param <T>
      * @return
      */
+    // tag::refguide[]
     <T> List<T> allInstances(Class<T> ofType, long start, long count);
 
+    // end::refguide[]
     /**
      * As {@link #allMatches(Class, Predicate, long, long)}, but returning all instances rather than just those
      * within the specified range.
      */
+    // tag::refguide[]
     <T> List<T> allMatches(Class<T> ofType, Predicate<? super T> predicate);
 
+    // end::refguide[]
     /**
      * Returns all the instances of the specified type (including subtypes) that
      * the predicate object accepts. If the optional range parameters are used, the
@@ -139,8 +158,10 @@ public interface RepositoryService {
      * @param <T>
      * @return
      */
+    // tag::refguide[]
     <T> List<T> allMatches(Class<T> ofType, Predicate<? super T> predicate, long start, long count);
 
+    // end::refguide[]
     /**
      * Returns all the instances that match the given {@link Query}.
      *
@@ -155,8 +176,10 @@ public interface RepositoryService {
      *     This method is the recommended way of querying for multiple instances.
      * </p>
      */
+    // tag::refguide[]
     <T> List<T> allMatches(Query<T> query);
 
+    // end::refguide[]
     /**
      * Find the only instance of the specified type (including subtypes) that
      * has the specified title.
@@ -171,8 +194,10 @@ public interface RepositoryService {
      * instances.  Use {@link #uniqueMatch(Query)} for production code.
      * </p>
      */
+    // tag::refguide[]
     <T> Optional<T> uniqueMatch(Class<T> ofType, Predicate<T> predicate);
 
+    // end::refguide[]
     /**
      * Find the only instance that matches the provided query.
      *
@@ -187,8 +212,10 @@ public interface RepositoryService {
      *
      * @see #firstMatch(Query)
      */
+    // tag::refguide[]
     <T> Optional<T> uniqueMatch(Query<T> query);
 
+    // end::refguide[]
     /**
      * Find the only instance of the specified type (including subtypes) that
      * has the specified title.
@@ -203,8 +230,10 @@ public interface RepositoryService {
      * instances.  Use {@link #firstMatch(Query)} for production code.
      * </p>
      */
+    // tag::refguide[]
     <T> Optional<T> firstMatch(Class<T> ofType, Predicate<T> predicate);
 
+    // end::refguide[]
     /**
      * Find the only instance that matches the provided query, if any..
      *
@@ -215,8 +244,9 @@ public interface RepositoryService {
      *
      * @see #firstMatch(Query)
      */
+    // tag::refguide[]
     <T> Optional<T> firstMatch(Query<T> query);
-// end::refguide[]
+    // end::refguide[]
 
     // -- DEPRECATIONS
 
@@ -254,6 +284,7 @@ public interface RepositoryService {
         return entityState.isDestroyed();
     }
 
-// tag::refguide[]
+    // tag::refguide[]
+
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/routing/RoutingService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/routing/RoutingService.java
index 6ec398d..a4574b3 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/routing/RoutingService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/routing/RoutingService.java
@@ -27,7 +27,6 @@ import org.apache.isis.applib.annotation.Programmatic;
 public interface RoutingService {
 
     boolean canRoute(Object original);
-
     Object route(Object original);
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/scratchpad/Scratchpad.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/scratchpad/Scratchpad.java
index 02afebe..a8dbd20 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/scratchpad/Scratchpad.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/scratchpad/Scratchpad.java
@@ -55,7 +55,7 @@ import lombok.extern.log4j.Log4j2;
 @Log4j2
 public class Scratchpad {
 
-// end::refguide[]
+    // end::refguide[]
     public Scratchpad(){
         log.debug("init");
     }
@@ -70,29 +70,37 @@ public class Scratchpad {
         log.debug("preDestroy");
     }
 
-// tag::refguide[]
+    // end::refguide[]
     /**
      * Provides a mechanism for each object being acted upon to pass
      * data to the next object.
      */
+    // tag::refguide[]
     private final Map<Object, Object> userData = _Maps.newHashMap();
 
+    // end::refguide[]
     /**
      * Obtain user-data, as set by a previous object being acted upon.
      */
+    // tag::refguide[]
     public Object get(Object key) {
         return userData.get(key);
     }
+
+    // end::refguide[]
     /**
      * Set user-data, for the use of a subsequent object being acted upon.
      */
+    // tag::refguide[]
     public void put(Object key, Object value) {
         userData.put(key, value);
     }
 
+    // end::refguide[]
     /**
      * Clear any user data.
      */
+    // tag::refguide[]
     public void clear() {
         userData.clear();
     }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/session/SessionLoggingService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/session/SessionLoggingService.java
index 7260ae0..31acc4e 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/session/SessionLoggingService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/session/SessionLoggingService.java
@@ -41,10 +41,9 @@ public interface SessionLoggingService {
     }
 
     void log(Type type, String username, Date date, CausedBy causedBy, String sessionId);
+    // end::refguide[]
 
-// end::refguide[]
-
-// tag::refguide-1[]
+    // tag::refguide-1[]
     class Stderr implements SessionLoggingService {
 
         @Override
@@ -65,7 +64,9 @@ public interface SessionLoggingService {
             System.err.println(logMessage);
         }
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-1[]
+
+    // tag::refguide[]
+
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/sudo/SudoService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/sudo/SudoService.java
index 335c5d5..afbbad5 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/sudo/SudoService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/sudo/SudoService.java
@@ -27,51 +27,64 @@ import org.apache.isis.applib.services.user.UserService;
 
 /**
  * Intended only for use by fixture scripts and integration tests, allows a block of code to execute
- * while the {@link org.apache.isis.applib.DomainObjectContainer container}'s
- * {@link UserService#getUser() getUser()} method returns the specified user/role as the effective user.
+ * while the {@link UserService}'s {@link UserService#getUser() getUser()} method returns the specified user/role
+ * as the effective user.
  */
 // tag::refguide[]
 public interface SudoService {
 
+    // end::refguide[]
     /**
      * If included in the list of roles, then will disable security checks (can view and use all object members).
      */
+    // tag::refguide[]
     String ACCESS_ALL_ROLE = SudoService.class.getName() + "#accessAll";
 
+    // end::refguide[]
     /**
-     * Executes the supplied block, with the {@link DomainObjectContainer} returning the specified user.
+     * Executes the supplied block, with the {@link UserService} returning the specified user.
      *
      * <p>
      *    The roles of this user will be the same as the currently logged-in user.
      * </p>
      */
+    // tag::refguide[]
     void sudo(String username, final Runnable runnable);
 
+    // end::refguide[]
     /**
-     * Executes the supplied block, with the {@link DomainObjectContainer} returning the specified user.
+     * Executes the supplied block, with the {@link UserService} returning the specified user.
      *
      * <p>
      *    The roles of this user will be the same as the currently logged-in user.
      * </p>
      */
+    // tag::refguide[]
     <T> T sudo(String username, final Callable<T> callable);
 
+    // end::refguide[]
     /**
-     * Executes the supplied block, with the {@link DomainObjectContainer} returning the specified user with the specified roles.
+     * Executes the supplied block, with the {@link UserService} returning the specified user with the specified roles.
      */
+    // tag::refguide[]
     void sudo(String username, List<String> roles, final Runnable runnable);
 
+    // end::refguide[]
     /**
-     * Executes the supplied block, with the {@link DomainObjectContainer} returning the specified user with the specified roles.
+     * Executes the supplied block, with the {@link UserService} returning the specified user with the specified roles.
      */
+    // tag::refguide[]
     <T> T sudo(String username, List<String> roles, final Callable<T> callable);
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+
+    // tag::refguide-1[]
     /**
      * Allows the {@link SudoService} to notify other services/components that the effective user has been changed.
      */
     interface Spi {
+
+        // end::refguide-1[]
         /**
          * Any implementation of the {@link SudoService} should call this method on all implementations of the
          * {@link Spi} service whenever {@link SudoService#sudo(String, List, Callable)} (or its overloads)
@@ -81,15 +94,14 @@ public interface SudoService {
          *     Modelled after Shiro security's <a href="https://shiro.apache.org/static/1.2.6/apidocs/org/apache/shiro/subject/Subject.html#runAs-org.apache.shiro.subject.PrincipalCollection-">runAs</a> support.
          * </p>
          */
-        @Programmatic
+        // tag::refguide-1[]
         void runAs(String username, List<String> roles);
 
-        /**
-         *
-         */
         void releaseRunAs();
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-1[]
+
+    // tag::refguide[]
+
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/swagger/SwaggerService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/swagger/SwaggerService.java
index 17b7150..15ba710 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/swagger/SwaggerService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/swagger/SwaggerService.java
@@ -28,9 +28,11 @@ import org.apache.isis.applib.annotation.ViewModel;
 // tag::refguide[]
 public interface SwaggerService {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide[]
     enum Visibility {
+
+        // end::refguide[]
         /**
          * Specification for use by third-party clients, ie public use.
          *
@@ -39,7 +41,10 @@ public interface SwaggerService {
          * of {@link NatureOfService#VIEW_REST_ONLY}.
          * </p>
          */
+        // tag::refguide[]
         PUBLIC,
+
+        // end::refguide[]
         /**
          * Specification for use only by internally-managed clients, ie private internal use.
          *
@@ -48,23 +53,28 @@ public interface SwaggerService {
          * </p>
          */
         PRIVATE,
+
+        // end::refguide[]
         /**
          * As {@link #PRIVATE}, also including any prototype actions (where {@link Action#restrictTo()} set to
          * {@link RestrictTo#PROTOTYPING}).
          */
-        PRIVATE_WITH_PROTOTYPING;
+        PRIVATE_WITH_PROTOTYPING
+        // end::refguide[]
+        ;
 
         public boolean isPublic() {
             return this == PUBLIC;
         }
+        // tag::refguide[]
+
     }
-// end::refguide-1[]
-// tag::refguide[]
 
     enum Format {
         JSON,
-        YAML;
-// end::refguide[]
+        YAML
+        // end::refguide[]
+        ;
         /**
          * Implementation note: not using subclasses, otherwise the key in translations.po becomes more complex.
          */
@@ -75,7 +85,7 @@ public interface SwaggerService {
                 return "application/yaml";
             }
         }
-// tag::refguide[]
+        // tag::refguide[]
     }
 
     String generateSwaggerSpec(final Visibility visibility, final Format format);
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/tablecol/TableColumnOrderService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/tablecol/TableColumnOrderService.java
index e2586d3..3c73edc 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/tablecol/TableColumnOrderService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/tablecol/TableColumnOrderService.java
@@ -42,8 +42,5 @@ public interface TableColumnOrderService {
             final Class<?> collectionType,
             final List<String> propertyIds);
 
-// end::refguide[]
-    // tag::refguide[]
-
 }
 // end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/title/TitleService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/title/TitleService.java
index 3b5ab71..38e4e6f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/title/TitleService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/title/TitleService.java
@@ -22,16 +22,20 @@ package org.apache.isis.applib.services.title;
 // tag::refguide[]
 public interface TitleService {
 
+    // end::refguide[]
     /**
      * Return the title of the object, as rendered in the UI by the
      * Isis viewers.
      */
+    // tag::refguide[]
     String titleOf(Object domainObject);
 
+    // end::refguide[]
     /**
      * Return the icon name of the object, as rendered in the UI by the
      * Isis viewers.
      */
+    // tag::refguide[]
     String iconNameOf(Object domainObject);
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/urlencoding/UrlEncodingService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/urlencoding/UrlEncodingService.java
index 3a2e053..219d9f9 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/urlencoding/UrlEncodingService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/urlencoding/UrlEncodingService.java
@@ -29,6 +29,7 @@ public interface UrlEncodingService extends EncoderDecoder {
 
     @Override
     String encode(final byte[] bytes);
+
     @Override
     byte[] decode(String str);
 
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/user/UserService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/user/UserService.java
index 73682c2..5a6e855 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/user/UserService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/user/UserService.java
@@ -24,9 +24,11 @@ import org.apache.isis.applib.security.UserMemento;
 // tag::refguide[]
 public interface UserService {
 
+    // end::refguide[]
     /**
      * Get the details about the current user.
      */
+    // tag::refguide[]
     UserMemento getUser();
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/userprof/UserProfileService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/userprof/UserProfileService.java
index e4934fa..57a7415 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/userprof/UserProfileService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/userprof/UserProfileService.java
@@ -31,6 +31,7 @@ import org.apache.isis.applib.annotation.Programmatic;
 // tag::refguide[]
 public interface UserProfileService {
 
+    // end::refguide[]
     /**
      * Used as the menu name of the {@link org.apache.isis.applib.annotation.DomainServiceLayout.MenuBar#TERTIARY tertiary}
      * &quot;Me&quot; menu bar.
@@ -39,6 +40,7 @@ public interface UserProfileService {
      *     If returns <tt>null</tt>, then the current user name is used instead.
      * </p>
      */
+    // tag::refguide[]
     String userProfileName();
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/userreg/EmailNotificationService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/userreg/EmailNotificationService.java
index 3d1a859..1e118b1 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/userreg/EmailNotificationService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/userreg/EmailNotificationService.java
@@ -35,18 +35,18 @@ import org.apache.isis.applib.services.userreg.events.PasswordResetEvent;
  * </p>
  */
 // tag::refguide[]
-public interface EmailNotificationService extends Serializable {
-
-    @PostConstruct
-    void init() ;
+public interface EmailNotificationService
+                            extends Serializable {
 
     boolean send(EmailRegistrationEvent ev);
 
     boolean send(PasswordResetEvent ev);
 
+    // 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/userreg/UserDetails.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/userreg/UserDetails.java
index 2e1f642..167a599 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/userreg/UserDetails.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/userreg/UserDetails.java
@@ -27,7 +27,8 @@ import lombok.Setter;
  * A model object for the signup page
  */
 // tag::refguide[]
-public class UserDetails implements Serializable {
+public class UserDetails
+                implements Serializable {
 
     private static final long serialVersionUID = -7308102332765149525L;
 
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/WrapperFactory.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/WrapperFactory.java
index 494215a..e903e32 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/WrapperFactory.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/WrapperFactory.java
@@ -29,6 +29,7 @@ import org.apache.isis.core.commons.collections.ImmutableEnumSet;
 
 import lombok.AccessLevel;
 import lombok.RequiredArgsConstructor;
+import lombok.experimental.UtilityClass;
 
 /**
  * Provides the ability to &quot;wrap&quot; of a domain object such that it can
@@ -71,67 +72,85 @@ import lombok.RequiredArgsConstructor;
 // tag::refguide[]
 public interface WrapperFactory {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
     /**
      * Whether interactions with the wrapper are actually passed onto the
      * underlying domain object.
      *
-     * @see WrapperFactory#wrap(Object, ExecutionMode)
+     * @see WrapperFactory#wrap(Object, ImmutableEnumSet)
      */
+    // tag::refguide-1[]
     @RequiredArgsConstructor(access = AccessLevel.PRIVATE)
     enum ExecutionMode {
 
+        // end::refguide-1[]
         /**
          * Skip all business rules.
          */
+        // tag::refguide-1[]
         SKIP_RULE_VALIDATION,
 
+        // end::refguide-1[]
         /**
          * Skip execution.
          */
+        // tag::refguide-1[]
         SKIP_EXECUTION,
 
+        // end::refguide-1[]
         /**
          * Don't fail fast, swallow any exception during validation or execution.
          */
+        // tag::refguide-1[]
         SWALLOW_EXCEPTIONS,
 
-        ;
+    }
+    // end::refguide-1[]
 
-        // -- PRESET ENUM SETS
+    // tag::refguide-2[]
+    @UtilityClass
+    class ExecutionModes {
 
+        // end::refguide-2[]
         /**
          * Validate all business rules and then execute. May throw exceptions in order to fail fast.
          */
+        // tag::refguide-2[]
         public static final ImmutableEnumSet<ExecutionMode> EXECUTE = ImmutableEnumSet.noneOf(ExecutionMode.class);
 
+        // end::refguide-2[]
         /**
          * Skip all business rules and then execute, does throw an exception if execution fails.
          */
-        public static final ImmutableEnumSet<ExecutionMode> SKIP_RULES = ImmutableEnumSet.of(SKIP_RULE_VALIDATION);
+        // tag::refguide-2[]
+        public static final ImmutableEnumSet<ExecutionMode> SKIP_RULES = ImmutableEnumSet.of(ExecutionMode.SKIP_RULE_VALIDATION);
 
+        // end::refguide-2[]
         /**
          * Validate all business rules but do not execute, throw an exception if validation
          * fails.
          */
-        public static final ImmutableEnumSet<ExecutionMode> NO_EXECUTE = ImmutableEnumSet.of(SKIP_EXECUTION);
+        // tag::refguide-2[]
+        public static final ImmutableEnumSet<ExecutionMode> NO_EXECUTE = ImmutableEnumSet.of(ExecutionMode.SKIP_EXECUTION);
 
+        // end::refguide-2[]
         /**
          * Validate all business rules and then execute, but don't throw an exception if validation
          * or execution fails.
          */
-        public static final ImmutableEnumSet<ExecutionMode> TRY = ImmutableEnumSet.of(SWALLOW_EXCEPTIONS);
+        // tag::refguide-2[]
+        public static final ImmutableEnumSet<ExecutionMode> TRY = ImmutableEnumSet.of(ExecutionMode.SWALLOW_EXCEPTIONS);
 
+        // end::refguide-2[]
         /**
          * Skips all steps.
          * @since 2.0
          */
-        public static final ImmutableEnumSet<ExecutionMode> NOOP = ImmutableEnumSet.of(SKIP_RULE_VALIDATION, SKIP_EXECUTION);
+        // tag::refguide-2[]
+        public static final ImmutableEnumSet<ExecutionMode> NOOP = ImmutableEnumSet.of(ExecutionMode.SKIP_RULE_VALIDATION, ExecutionMode.SKIP_EXECUTION);
 
     }
-// end::refguide-1[]
-// tag::refguide[]
+    // end::refguide-2[]
 
     /**
      * Provides the &quot;wrapper&quot; of the underlying domain object.
@@ -140,31 +159,41 @@ public interface WrapperFactory {
      * If the object has (see {@link #isWrapper(Object)} already been wrapped),
      * then should just return the object back unchanged.
      */
+    // tag::refguide[]
     <T> T wrap(T domainObject);
 
+    // end::refguide[]
     /**
      * {@link #wrap(Object) wraps} a {@link FactoryService#mixin(Class, Object) mixin}.
      */
+    // tag::refguide[]
     <T> T wrapMixin(Class<T> mixinClass, Object mixedIn);
 
+    // end::refguide[]
     /**
-     * Convenience method for {@link #wrap(Object, ExecutionMode)} with {@link ExecutionMode#TRY},
+     * Convenience method for {@link #wrap(Object, ImmutableEnumSet)} with {@link ExecutionModes#TRY},
      * to make this feature more discoverable.
      */
+    // tag::refguide[]
     <T> T wrapTry(T domainObject);
 
+    // end::refguide[]
     /**
-     * Convenience method for {@link #wrap(Object, ExecutionMode)} with {@link ExecutionMode#NO_EXECUTE},
+     * Convenience method for {@link #wrap(Object, ImmutableEnumSet)} with {@link ExecutionModes#NO_EXECUTE},
      * to make this feature more discoverable.
      */
+    // tag::refguide[]
     <T> T wrapNoExecute(T domainObject);
 
+    // end::refguide[]
     /**
-     * Convenience method for {@link #wrap(Object, ExecutionMode)} with {@link ExecutionMode#SKIP_RULES},
+     * Convenience method for {@link #wrap(Object, ImmutableEnumSet)} with {@link ExecutionModes#SKIP_RULES},
      * to make this feature more discoverable.
      */
+    // tag::refguide[]
     <T> T wrapSkipRules(T domainObject);
 
+    // end::refguide[]
     /**
      * Same as {@link #wrap(Object)}, except the actual execution occurs only if
      * the <tt>execute</tt> parameter indicates.
@@ -173,9 +202,10 @@ public interface WrapperFactory {
      * Otherwise, will do all the validations (raise exceptions as required
      * etc.), but doesn't modify the model.
      */
+    // tag::refguide[]
     <T> T wrap(T domainObject, ImmutableEnumSet<ExecutionMode> mode);
 
-
+    // end::refguide[]
     /**
      * Obtains the underlying domain object, if wrapped.
      *
@@ -183,9 +213,10 @@ public interface WrapperFactory {
      * If the object {@link #isWrapper(Object) is not wrapped}, then
      * should just return the object back unchanged.
      */
+    // tag::refguide[]
     <T> T unwrap(T possibleWrappedDomainObject);
 
-
+    // end::refguide[]
     /**
      * Whether the supplied object has been wrapped.
      *
@@ -194,9 +225,14 @@ public interface WrapperFactory {
      *            - object that might or might not be a wrapper.
      * @return
      */
+    // tag::refguide[]
     <T> boolean isWrapper(T possibleWrappedDomainObject);
 
+    // end::refguide[]
+
+    //
     // -- ASYNC WRAPPING
+    //
 
     /**
      * Returns a {@link AsyncWrap} bound to the provided {@code domainObject},
@@ -208,20 +244,29 @@ public interface WrapperFactory {
      *
      * @since 2.0
      */
+    // tag::refguide[]
     <T> AsyncWrap<T> async(T domainObject, ImmutableEnumSet<ExecutionMode> mode);
 
+    // end::refguide[]
     /**
-     * Shortcut for {@link #async(Object, EnumSet)} using execution mode
-     * {@link ExecutionMode#EXECUTE}.
+     * Shortcut for {@link #async(Object, ImmutableEnumSet)} using execution mode
+     * {@link ExecutionModes#EXECUTE}.
      * @param <T>
      * @param domainObject
      *
      * @since 2.0
      */
+    // tag::refguide[]
     default <T> AsyncWrap<T> async(T domainObject) {
-        return async(domainObject, ExecutionMode.EXECUTE);
+        // end::refguide[]
+
+        return async(domainObject, ExecutionModes.EXECUTE);
+
+        // tag::refguide[]
+        // ...
     }
 
+    // end::refguide[]
     /**
      * Returns a {@link AsyncWrap} bound to the provided {@code mixinClass},
      * to prepare for type-safe asynchronous action execution.
@@ -233,29 +278,43 @@ public interface WrapperFactory {
      *
      * @since 2.0
      */
+    // tag::refguide[]
     <T> AsyncWrap<T> asyncMixin(Class<T> mixinClass, Object mixedIn, ImmutableEnumSet<ExecutionMode> mode);
 
+    // end::refguide[]
     /**
-     * Shortcut for {@link #asyncMixin(Class, Object, EnumSet)} using execution mode
-     * {@link ExecutionMode#EXECUTE}.
+     * Shortcut for {@link #asyncMixin(Class, Object, ImmutableEnumSet)} using execution mode
+     * {@link ExecutionModes#EXECUTE}.
      * @param <T>
      * @param mixinClass
      * @param mixedIn
      *
      * @since 2.0
      */
+    // tag::refguide[]
     default <T> AsyncWrap<T> asyncMixin(Class<T> mixinClass, Object mixedIn) {
-        return asyncMixin(mixinClass, mixedIn, ExecutionMode.EXECUTE);
+        // end::refguide[]
+
+        return asyncMixin(mixinClass, mixedIn, ExecutionModes.EXECUTE);
+
+        // tag::refguide[]
+        // ...
     }
+    // end::refguide[]
+
 
+    //
     // -- ITERACTION EVENT HANDLING
+    //
 
     /**
      * All {@link InteractionListener}s that have been registered using
      * {@link #addInteractionListener(InteractionListener)}.
      */
+    // tag::refguide[]
     List<InteractionListener> getListeners();
 
+    // end::refguide[]
     /**
      * Registers an {@link InteractionListener}, to be notified of interactions
      * on all wrappers.
@@ -269,8 +328,10 @@ public interface WrapperFactory {
      * @param listener
      * @return
      */
+    // tag::refguide[]
     boolean addInteractionListener(InteractionListener listener);
 
+    // end::refguide[]
     /**
      * Remove an {@link InteractionListener}, to no longer be notified of
      * interactions on wrappers.
@@ -284,6 +345,7 @@ public interface WrapperFactory {
      * @param listener
      * @return
      */
+    // tag::refguide[]
     boolean removeInteractionListener(InteractionListener listener);
 
     void notifyListeners(InteractionEvent ev);
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/WrappingObject.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/WrappingObject.java
index 6e12f63..9c936cf 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/WrappingObject.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/WrappingObject.java
@@ -27,8 +27,10 @@ import org.apache.isis.core.commons.collections.ImmutableEnumSet;
  * Implemented by all objects that have been viewed as per
  * {@link org.apache.isis.applib.services.wrapper.WrapperFactory#wrap(Object)}.
  */
+// tag::refguide[]
 public interface WrappingObject {
 
+    // end::refguide[]
     /**
      * Programmatic equivalent of invoking save for a transient object .
      *
@@ -37,8 +39,10 @@ public interface WrappingObject {
      * intended to reduce the risk of a collision.
      * </p>
      */
+    // tag::refguide[]
     void __isis_save();
 
+    // end::refguide[]
     /**
      * Provide access to the underlying, wrapped object.
      *
@@ -56,17 +60,22 @@ public interface WrappingObject {
      * <b>NOTE: there is a string-literal reference to this name
      * <tt>DomainObjectInvocationHandler</tt>, so it should not be changed.</b>.
      */
+    // tag::refguide[]
     Object __isis_wrapped();
 
+    // end::refguide[]
     /**
      * The {@link EnumSet<WrapperFactory.ExecutionMode> execution mode}
      * with which this wrapper was
-     * {@link WrapperFactory#wrap(Object, EnumSet) created}.
+     * {@link WrapperFactory#wrap(Object, ImmutableEnumSet) created}.
      *
      * <p>
      * NOTE: domain classes may not have a method with this name.  The <tt>__isis_</tt> prefix is
      * intended to reduce the risk of a collision.
      * </p>
      */
+    // tag::refguide[]
     ImmutableEnumSet<WrapperFactory.ExecutionMode> __isis_executionMode();
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/events/InteractionEvent.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/events/InteractionEvent.java
index 50d3f48..ea74096 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/events/InteractionEvent.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/wrapper/events/InteractionEvent.java
@@ -22,7 +22,7 @@ package org.apache.isis.applib.services.wrapper.events;
 import java.util.List;
 
 import org.apache.isis.applib.Identifier;
-import org.apache.isis.applib.events.domain.EventObjectBase;
+import org.apache.isis.applib.events.EventObjectBase;
 
 /**
  * <i>Supported only by {@link org.apache.isis.applib.services.wrapper.WrapperFactory} service, </i> 
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/Transaction.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/Transaction.java
index 257a64d..7ba0a5f 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/Transaction.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/Transaction.java
@@ -29,6 +29,7 @@ public interface Transaction {
 
     TransactionId getId();
 
+    // end::refguide[]
     /**
      * Flush all changes to the object store.
      *
@@ -41,6 +42,7 @@ public interface Transaction {
      *     Equivalent to {@link TransactionService#flushTransaction()}.
      * </p>
      */
+    // tag::refguide[]
     void flush();
 
     TransactionState getTransactionState();
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionId.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionId.java
index 9353115..8536f13 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionId.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionId.java
@@ -24,22 +24,28 @@ import org.apache.isis.applib.services.HasUniqueId;
 
 import lombok.Data;
 
+// tag::refguide[]
 @Data(staticConstructor = "of")
 public final class TransactionId implements HasUniqueId {
 
     private final UUID uniqueId;
 
+    // end::refguide[]
     /**
-     * The {@link HasUniqueId#getUniqueId()} is (as of 1.13.0) actually an identifier for the request/
-     * interaction, and there can actually be multiple transactions within such a request/interaction.  
+     * The {@link HasUniqueId#getUniqueId()} is actually an identifier for the request/
+     * interaction, and there can actually be multiple transactions within such a request/interaction.
      * The sequence (0-based) is used to distinguish such.
      */
+    // tag::refguide[]
     private final int sequence;
 
-    private static final TransactionId EMPTY = TransactionId.of(UUID.fromString("0000-00-00-00-000000"), 0); 
+    // end::refguide[]
+    private static final TransactionId EMPTY = TransactionId.of(UUID.fromString("0000-00-00-00-000000"), 0);
 
     public static TransactionId empty() {
         return EMPTY;
     }
 
+    // tag::refguide[]
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionService.java
index 4c1e19c..27264a9 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionService.java
@@ -27,13 +27,17 @@ import java.util.function.Supplier;
 // tag::refguide[]
 public interface TransactionService {
 
+    // end::refguide[]
     /**
-     * When called within an existing transactional boundary returns an unique id,
+     * When called within an existing transactional boundary returns the unique identifier to the transaction,
      * {@code null} otherwise.
+     *
      * @return nullable
      */
+    // tag::refguide[]
     TransactionId currentTransactionId();
 
+    // end::refguide[]
     /**
      * Flush all changes to the object store.
      *
@@ -41,43 +45,51 @@ public interface TransactionService {
      * Occasionally useful to ensure that newly persisted domain objects
      * are flushed to the database prior to a subsequent repository query.
      * </p>
-     *
-     * <p>
-     *     Equivalent to {@link Transaction#flush()} (with {@link Transaction} obtained using {@link #currentTransaction()}).
-     * </p>
      */
+    // tag::refguide[]
     void flushTransaction();
 
+    // end::refguide[]
     /**
-     * Generally this is equivalent to using {@link #currentTransaction()} and {@link Transaction#getTransactionState()}.
-     * However, if there is no current transaction, then this will return {@link TransactionState#NONE}.
+     * @return - the state of the current transaction.  If there is no current transaction, then returns {@link TransactionState#NONE}.
      */
+    // tag::refguide[]
     TransactionState currentTransactionState();
 
+    // end::refguide[]
     /**
      * Runs given {@code task} within an existing transactional boundary, or in the absence of such a
      * boundary creates a new one.
+     *
      * @param task
      */
+    // tag::refguide[]
     void executeWithinTransaction(Runnable task);
 
+    // end::refguide[]
     /**
      * Runs given {@code task} within an existing transactional boundary, or in the absence of such a
      * boundary creates a new one.
+     *
      * @param task
      */
+    // tag::refguide[]
     <T> T executeWithinTransaction(Supplier<T> task);
 
+    // end::refguide[]
     /**
      * Runs given {@code task} within its own (new) transactional boundary.
      * @param task
      */
+    // tag::refguide[]
     void executeWithinNewTransaction(Runnable task);
 
+    // end::refguide[]
     /**
      * Runs given {@code task} within its own (new) transactional boundary.
      * @param task
      */
+    // tag::refguide[]
     <T> T executeWithinNewTransaction(Supplier<T> task);
 
 }
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionState.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionState.java
index 187ed7d..d1be4e4 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionState.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/xactn/TransactionState.java
@@ -18,19 +18,27 @@
  */
 package org.apache.isis.applib.services.xactn;
 
+// tag::refguide[]
 public enum TransactionState {
 
+    // end::refguide[]
     /**
      * No transaction exists.
      */
+    // tag::refguide[]
     NONE,
+
+    // end::refguide[]
     /**
      * Started, still in progress.
      * <p/>
      * <p/>
      * May flush, commit or abort.
      */
+    // tag::refguide[]
     IN_PROGRESS,
+
+    // end::refguide[]
     /**
      * Started, but has hit an exception.
      * <p/>
@@ -41,21 +49,31 @@ public enum TransactionState {
      * <p/>
      * Similar to <tt>setRollbackOnly</tt> in EJBs.
      */
+    // tag::refguide[]
     MUST_ABORT,
+
+    // end::refguide[]
     /**
      * Completed, having successfully committed.
      * <p/>
      * <p/>
      * May not flush or abort or commit (will throw {@link IllegalStateException}).
      */
+    // tag::refguide[]
     COMMITTED,
+
+    // end::refguide[]
     /**
      * Completed, having aborted.
      * <p/>
      * <p/>
      * May not flush, commit or abort (will throw {@link IllegalStateException}).
      */
-    ABORTED;
+    // tag::refguide[]
+    ABORTED
+
+    // end::refguide[]
+    ;
 
     private TransactionState() {
     }
@@ -91,4 +109,8 @@ public enum TransactionState {
     public boolean mustAbort() {
         return this == MUST_ABORT;
     }
+
+    // tag::refguide[]
+
 }
+// end::refguide[]
diff --git a/api/applib/src/main/adoc/modules/applib-svc/examples/services/xmlsnapshot/XmlSnapshotService.java b/api/applib/src/main/adoc/modules/applib-svc/examples/services/xmlsnapshot/XmlSnapshotService.java
index 0621a0a..88e6bd9 100644
--- a/api/applib/src/main/adoc/modules/applib-svc/examples/services/xmlsnapshot/XmlSnapshotService.java
+++ b/api/applib/src/main/adoc/modules/applib-svc/examples/services/xmlsnapshot/XmlSnapshotService.java
@@ -35,8 +35,8 @@ import org.apache.isis.applib.annotation.Programmatic;
 // tag::refguide[]
 public interface XmlSnapshotService {
 
-// end::refguide[]
-// tag::refguide-1[]
+    // end::refguide[]
+    // tag::refguide-1[]
     interface Snapshot {
         Document getXmlDocument();
         Document getXsdDocument();
@@ -44,17 +44,17 @@ public interface XmlSnapshotService {
         String getXmlDocumentAsString();
         String getXsdDocumentAsString();
     }
-// end::refguide-1[]
+    // end::refguide-1[]
 
-// tag::refguide-2[]
+    // tag::refguide-2[]
     interface Builder {
         void includePath(final String path);
         void includePathAndAnnotation(final String path, final String annotation);
         XmlSnapshotService.Snapshot build();
     }
-// end::refguide-2[]
+    // end::refguide-2[]
 
-// tag::refguide-3[]
+    // tag::refguide-3[]
     class Exception extends RuntimeException {
 
         private static final long serialVersionUID = 1L;
@@ -75,32 +75,40 @@ public interface XmlSnapshotService {
             super(cause);
         }
     }
-// end::refguide-3[]
+    // end::refguide-3[]
 
-// tag::refguide[]
+    // tag::refguide[]
     XmlSnapshotService.Snapshot snapshotFor(final Object domainObject);
 
     XmlSnapshotService.Builder builderFor(final Object domainObject);
 
+    // end::refguide[]
     /**
      * Convenience to convert xml string (eg as obtained by {@link Snapshot#getXmlDocumentAsString()} or
      * {@link Snapshot#getXsdDocumentAsString()}) back into a {@link Document W3C Document}.
      */
+    // tag::refguide[]
     Document asDocument(String xmlStr);
 
+    // end::refguide[]
     /**
      * Convenience method to extract value of an XML element, based on its type.
      */
+    // tag::refguide[]
     <T> T getChildElementValue(final Element el, final String tagname, final Class<T> expectedCls);
 
+    // end::refguide[]
     /**
      * Convenience method to walk XML document.
      */
+    // tag::refguide[]
     Element getChildElement(final Element el, final String tagname);
 
+    // end::refguide[]
     /**
      * Convenience method to obtain value of child text node.
      */
+    // tag::refguide[]
     String getChildTextValue(final Element el);
 
 }