[7/8] isis git commit: ISIS-1299: updated documentation.

[da...@apache.org]

ISIS-1299: updated documentation.


Project: http://git-wip-us.apache.org/repos/asf/isis/repo
Commit: http://git-wip-us.apache.org/repos/asf/isis/commit/2c3a04cb
Tree: http://git-wip-us.apache.org/repos/asf/isis/tree/2c3a04cb
Diff: http://git-wip-us.apache.org/repos/asf/isis/diff/2c3a04cb

Branch: refs/heads/master
Commit: 2c3a04cb9b647938ec67eafcdb5d09e82ce2651f
Parents: 981d731
Author: Dan Haywood <da...@haywood-associates.co.uk>
Authored: Wed Mar 9 07:31:03 2016 +0000
Committer: Dan Haywood <da...@haywood-associates.co.uk>
Committed: Wed Mar 9 07:31:03 2016 +0000

----------------------------------------------------------------------
 .../main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc  | 13 +++++++++++++
 1 file changed, 13 insertions(+)
----------------------------------------------------------------------


http://git-wip-us.apache.org/repos/asf/isis/blob/2c3a04cb/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
----------------------------------------------------------------------
diff --git a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
index f4c3028..f3e53c1 100644
--- a/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
+++ b/adocs/documentation/src/main/asciidoc/guides/_ugbtb_view-models_jaxb.adoc
@@ -10,6 +10,19 @@ As noted in the xref:ugbtb.adoc#_ugbtb_view-models_use-cases[introduction], view
 JAXB annotations.  The serialized form of these view models is therefore XML, which also enables these view models
 to act as DTOs.
 
+In case it's not obvious, these DTOs are still usable as "regular" view models; they will render in the
+xref:ugvw.adoc#[Wicket viewer] just like any other.  In fact, these JAXB-annotated view models are in many regards the
+most powerful of all the various ways of writing view models:
+
+* their entire state (collections as well as properties) is automatically managed from interaction to interaction. +
++
+In contrast, using xref:rgant.adoc#_rgant_ViewModel[`@ViewModel`] (or its
+xref:rgant.adoc#_rgant_DomainObject_nature[`@DomainObject#nature()`] equivalent) will only manage the state of
+properties, but not collections.  And if using the xref:rgcms.adoc#_rgcms_classes_super_ViewModel[`ViewModel`]
+interface, then the programmer must write all the state management (lots of boilerplate).
+
+* (as of `1.12.0-SNAPSHOT`), JAXB-annotated view models are editable.
+
 The examples in this section uses the DTO for `ToDoItem`, taken from the (non-ASF) http://github.com/isisaddons/isis-app-todoapp[Isis addons' todoapp].  This DTO is defined as follows:
 
 [source,java]