Merge lp:~robert-ancell/ubuntu-ui-toolkit/statesaver-docs into lp:ubuntu-ui-toolkit

[Robert Ancell]

Fix some spelling/grammar mistakes and do some rewording to make documentation clearer

Fix some spelling and grammar mistakes in the documentation. I've also attempted to reword some sentences to be clearer.

In general, the StateSaver documentation is very difficult to understand. In particular:

- It talks about serialization which is a technical detail on how the data is stored but not something the API consumer actually sees.
- It talks about "component completion time", "deactivated" and "closed properly" but it's not clear exactly what these are / when they occur.
- It talks about "synchronizing" but it's not clear what's being synchronized.
- Don't know what an "attachee" is.

[Robert Ancell (robert-ancell)]

I also don't know what an "attached object" is.

[PS Jenkins bot (ps-jenkins)]

FAILED: Continuous integration, rev:1110
http://jenkins.qa.ubuntu.com/job/ubuntu-ui-toolkit-ci/2165/
Executed test runs:
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/generic-deb-autopilot-utopic-touch/5709
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-utopic/4008
    SUCCESS: http://jenkins.qa.ubuntu.com/job/ubuntu-ui-toolkit-utopic-amd64-ci/111
    SUCCESS: http://jenkins.qa.ubuntu.com/job/ubuntu-ui-toolkit-utopic-armhf-ci/111
        deb: http://jenkins.qa.ubuntu.com/job/ubuntu-ui-toolkit-utopic-armhf-ci/111/artifact/work/output/*zip*/output.zip
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/generic-deb-autopilot-runner-mako/5373
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-armhf/6961
        deb: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-armhf/6961/artifact/work/output/*zip*/output.zip
    SUCCESS: http://s-jenkins.ubuntu-ci:8080/job/touch-flash-device/14372
    UNSTABLE: http://jenkins.qa.ubuntu.com/job/autopilot-testrunner-otto-utopic/3377
    SUCCESS: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-amd64/4335
        deb: http://jenkins.qa.ubuntu.com/job/generic-mediumtests-builder-utopic-amd64/4335/artifact/work/output/*zip*/output.zip

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/ubuntu-ui-toolkit-ci/2165/rebuild

review: Needs Fixing (continuous-integration)

[Zsombor Egri (zsombi)]

First, thanks for fixing this! Let me answer these, perhaps we can make the docs more understandable.
> - It talks about serialization which is a technical detail on how the data is stored but not
> something the API consumer actually sees.

The property values are saved once the component is completed or when the application deactivates (see below what that means). It is restored to the saved state when the application is (re)started. The saved data is cleared once the application is closed properly.

> - It talks about "component completion time", "deactivated" and "closed properly" but it's not
> clear exactly what these are / when they occur.

Component completion time is well known in QML world.
An application is "deactivated" when it looses focus (goes background, in our case on device goes to sleep, but on desktop is simply background).
An application is "closed properly" when the user quits (on desktop) or "kills" the app from the task management parallax (on device). When the lifecycle management kills it, that's an improper app close. Or when an app is SIGTERM-ed or SIGINT-ed on desktop.

> - It talks about "synchronizing" but it's not clear what's being synchronised.

The example where this synchronisation is mentioned is where the StateSaver's enabled property is bound with the TextField's enabled, so when the TextField is disabled, the StateSaver will also be. I thought we can call this as synchronised, but hope you find a better explanation for it tbh... The idea is that StateSaver will not save any properties of the attached (below) is that one is disabled, but the state saver's enabled should also be driven independently from its attachee.

> - Don't know what an "attachee" is.

Attachee is the object (or item) to which the attached properties are attached :) Again, a QML term.
An attached object is the object which holds the attached properties (in our case StateSaver is the attached object, and the attached properties are "enabled" and "properties").

And last, please sync the MR with staging and re-submit this MR against that, and not agains trunk.
lp:~ubuntu-sdk-team/ubuntu-ui-toolkit/staging

Unmerged revisions

1110. By Robert Ancell on 2014-10-09

Fix some spelling/grammar mistakes and do some rewording to make documentation clearer

=== modified file 'modules/Ubuntu/Components/plugin/ucstatesaver.cpp'
--- modules/Ubuntu/Components/plugin/ucstatesaver.cpp	2014-09-03 16:12:24 +0000
+++ modules/Ubuntu/Components/plugin/ucstatesaver.cpp	2014-10-09 02:31:17 +0000
@@ -142,19 +142,19 @@
  * \instantiates UCStateSaverAttached
  * \inqmlmodule Ubuntu.Components 1.1
  * \ingroup ubuntu-services
- * \brief Attached propertyes to save component property states.
- *
- * StateSaver attached object provides the ability to save component property values
- * that can be restored after an inproper application close. The properties subject
- * of serialization must be given in the \l properties as a string, separated with
- * commas. The serialization will happen automatically on component's completion
- * time, as well as when the application is deactivated. Automatic serialization
- * of a component can be turned off by simply setting false to \l enabled property.
- *
- * \note The application name must be set correctly to the package name so that
- * state saving can work (e.g. com.ubuntu.calendar) through \l MainView::applicationName.
- *
- * States saved are discarded when the application is closed properly. The state
+ * \brief Attached properties to save component property states.
+ *
+ * The StateSaver attached object provides the ability to save component property values
+ * so they can be restored after an inproper application close. The names of the properties
+ * to be serialized are listed in the \l properties property.
+ * The storage will happen automatically at the component's completion
+ * time or when the application is deactivated. Automatic serialization
+ * of a component can be disabled by setting the \l enabled property to false.
+ *
+ * \note The application name must be set in \l MainView::applicationName and match the
+ * package name so that state saving can work (e.g. com.ubuntu.calendar).
+ *
+ * Saved states are discarded when the application is closed properly. The state
  * loading is ignored (but not discarded) when the application is launched through
  * UriHandler.
  *
@@ -187,10 +187,10 @@
  * \endqml
  *
  * StateSaver computes a unique identifier for the attachee using the component's
- * and all its parents' \a{id}. Therefore attachee component as well as all its
+ * and all its parents' \a{id}s. Therefore attachee component as well as all its
  * parents must have a valid ID set.
  *
- * The following example will give error for the \a input, as the root component
+ * The following example will give an error for \a input, as the root component
  * has no id specified:
  * \qml
  * Item {
@@ -223,7 +223,7 @@
  *
  * When used with Repeater, each created item from the Repeater's delegate will
  * be saved separately. Note that due to the way Repeater works, Repeaters do not
- * need to have id specified.
+ * need to have an id specified.
  *
  * \qml
  * Item {
@@ -265,7 +265,7 @@
 // getter/setter
 /*!
  * \qmlproperty bool StateSaver::enabled
- * The property drives the automatic state saving. When disabled, state saving
+ * This property drives the automatic state saving. When disabled, state saving
  * will not happen on properties.
  *
  * The default value is true.
@@ -292,7 +292,7 @@
  * List of properties to be serialized, separated with commas. Properties must be
  * writable and can only be \l{http://qt-project.org/doc/qt-5.0/qtqml/qtqml-typesystem-basictypes.html}{QML base types}.
  *
- * A custom singl eline input which saves the text, polaceholderText, font and color would look as follows:
+ * A custom single line input which saves the text, placeholderText, font and color would look as follows:
  * \qml
  * TextField {
  *     id: input