Merge lp:~michihenning/unity-scopes-api/category-doc into lp:unity-scopes-api/devel

[Michi Henning]

Updated doc to make it clear that generating unique category IDs for each query is a bad idea.

Updated doc to make it clear that generating unique category IDs for each query is a bad idea.

[PS Jenkins bot (ps-jenkins)]

PASSED: Continuous integration, rev:637
http://jenkins.qa.ubuntu.com/job/unity-scopes-api-devel-ci/1564/
Executed test runs:
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-devel-vivid-amd64-ci/173
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-devel-vivid-armhf-ci/173
        deb: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-devel-vivid-armhf-ci/173/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-devel-vivid-i386-ci/173
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-devel-wily-amd64-ci/105
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-devel-wily-armhf-ci/103
        deb: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-devel-wily-armhf-ci/103/artifact/work/output/*zip*/output.zip
    SUCCESS: http://jenkins.qa.ubuntu.com/job/unity-scopes-api-devel-wily-i386-ci/105

Click here to trigger a rebuild:
http://s-jenkins.ubuntu-ci:8080/job/unity-scopes-api-devel-ci/1564/rebuild

review: Approve (continuous-integration)

[Marcus Tomlinson (marcustomlinson)]

+1

review: Approve

=== modified file 'doc/tutorial.dox'
--- doc/tutorial.dox	2015-09-02 05:35:01 +0000
+++ doc/tutorial.dox	2015-10-29 02:41:52 +0000
@@ -323,6 +323,11 @@
 until your scope has processed _all_ results. To create a positive user experience,
 your scope should push results as soon as possible.
 
+The UI uses categories to incrementally render the display after a refresh of search results. This relies
+on categories staying the same from query to query. If your scope has, say, a "News" category, you need
+to make sure that the category ID and name stay the same from query to query. In particular, do _not_
+create category IDs that are artificially unique per query (such as by appending a sequence number).
+
 When you create a category, you can provide a \link unity::scopes::CategoryRenderer \endlink instance.
 The category renderer determines the visual appearance of the results in that category (such as
 display in a grid or in a carousel layout).

=== modified file 'include/unity/scopes/SearchReply.h'
--- include/unity/scopes/SearchReply.h	2015-02-12 07:22:26 +0000
+++ include/unity/scopes/SearchReply.h	2015-10-29 02:41:52 +0000
@@ -90,6 +90,10 @@
 
     \return The category instance
     \throws unity::scopes::InvalidArgumentException if category with that id has already been registered.
+
+    \note The UI uses category IDs for incremental rendering when refreshing search results. For this to work
+    correctly, you need to make sure that you use the same category ID for different queries if the search
+    results apply to the same category as for a previous search.
     */
     virtual Category::SCPtr register_category(std::string const& id,
                                               std::string const& title,