From e198ecdd6b1ec62ead343e7d87ed0c44f77ca21e Mon Sep 17 00:00:00 2001
From: ceee <cee@live.at>
Date: Tue, 17 Sep 2013 23:28:28 +0200
Subject: [PATCH] update docs

---
 PocketSharp.Website/index.html         | 66 ++++++++++++--------------
 PocketSharp/PocketSharp.nuspec         |  2 +-
 PocketSharp/Properties/AssemblyInfo.cs |  4 +-
 README.md                              | 50 +++++++++++--------
 4 files changed, 64 insertions(+), 58 deletions(-)

diff --git a/PocketSharp.Website/index.html b/PocketSharp.Website/index.html
index 7ac6902..4518de8 100644
--- a/PocketSharp.Website/index.html
+++ b/PocketSharp.Website/index.html
@@ -32,6 +32,8 @@
       </h1>
       <p class="app-description">
         PocketSharp is a C#.NET class library, that integrates the Pocket API v3
+        <br><br>
+        Current version: <b>1.2.0</b>
       </p>
       <div class="app-nuget">
         <code>Install-Package PocketSharp</code>
@@ -122,6 +124,8 @@ using PocketSharp.Models;</code></pre>
 
           <h2>Release History</h2>
         <ul>
+          <li>2013-09-17 v1.2.0 simplified retrieve methods</li>
+          <li>2013-09-17 v1.1.0 fix modification requests</li>
           <li>2013-09-15 v1.0.0 convert to PCL &amp; implement async</li>
           <li>2013-08-16 v0.3.2 tag modification fixed and full retrieval of items for Retrieve method</li>
           <li>2013-07-07 v0.3.1 authentication fixes</li>
@@ -186,42 +190,34 @@ Note that <code>GetAccessCode</code> can only be called with an existing <em>req
       <div data-part="retrieve">
 
         <h2>Retrieve</h2>
-        <p>Get list of all items:</p>
-
-          <pre class="language-clike"><code>List&lt;PocketItem&gt; items = await _client.Retrieve();
-// equivalent to: await _client.Retrieve(RetrieveFilter.All)</code></pre>
-
-        <p>Find items by a tag:</p>
-
-          <pre class="language-clike"><code>List&lt;PocketItem&gt; items = await _client.SearchByTag(&quot;tutorial&quot;);</code></pre>
-
-        <p>Find items by a search string:</p>
-
-          <pre class="language-clike"><code>List&lt;PocketItem&gt; items = await _client.Search(&quot;css&quot;);</code></pre>
-
-        <p>Find items by a filter:</p>
-
-          <pre class="language-clike"><code>List&lt;PocketItem&gt; items = await _client.Retrieve(RetrieveFilter.Favorite); // only favorites</code></pre>
-
-        <p>The RetrieveFilter Enum is specified as follows:</p>
-
-          <pre class="language-clike"><code>enum RetrieveFilter { All, Unread, Archive, Favorite, Article, Video, Image }</code></pre>
-
-        <h4>Custom Parameters</h4>
-        <p>You can create a completely custom parameter list for retrieval with the POCO <code>RetrieveParameters</code>:</p>
-
-          <pre class="language-clike"><code>
-var parameters = new RetrieveParameters()
-{
-	Count = 50,
-	Offset = 100,
-	Sort = SortEnum.oldest
-	...
-};
-List&lt;pocketitem&gt; items = await _client.Retrieve(parameters);
-</code></pre>
-
 
+<p>Get list of all items:</p>
+<p><pre class="language-clike"><code>List&lt;PocketItem&gt; items = await _client.Retrieve();
+// equivalent to: await _client.RetrieveByFilter(RetrieveFilter.All)</code></pre></p>
+<p>Get a list with specific parameters (explanation in the <a href="http://getpocket.com/developer/docs/v3/retrieve">Pocket Docs</a>):</p>
+<p><pre class="language-clike"><code>List&lt;PocketItem&gt; items = await _client.Retrieve(
+  State? state = null,
+  bool? favorite = null,
+  string tag = null,
+  ContentType? contentType = null,
+  Sort? sort = null,
+  string search = null,
+  string domain = null,
+  DateTime? since = null,
+  int? count = null,
+  int? offset = null
+);</code></pre></p>
+<p>It's best to use parameters as <em>named parameters</em>, to avoid typing <code>null</code> values:</p>
+<p><pre class="language-clike"><code>List&lt;PocketItem&gt; items = await _client.Retrieve(count: 10, offset: 20, sort: Sort.oldest);</code></pre></p>
+<p>Find items by a tag:</p>
+<p><pre class="language-clike"><code>List&lt;PocketItem&gt; items = await _client.SearchByTag(&quot;tutorial&quot;);</code></pre></p>
+<p>Find items by a search string:</p>
+<p><pre class="language-clike"><code>List&lt;PocketItem&gt; items = await _client.Search(&quot;css&quot;);</code></pre></p>
+<p>Get a filtered list:</p>
+<p><pre class="language-clike"><code>List&lt;PocketItem&gt; items = await _client.RetrieveByFilter(RetrieveFilter.Favorite);
+// returns favorites only</code></pre></p>
+<p>The RetrieveFilter Enum is specified as follows:</p>
+<p><pre class="language-clike"><code>enum RetrieveFilter { All, Unread, Archive, Favorite, Article, Video, Image }</code></pre></p>
       </div>
 
       <div data-part="add">
diff --git a/PocketSharp/PocketSharp.nuspec b/PocketSharp/PocketSharp.nuspec
index 4fb541b..645b7f0 100644
--- a/PocketSharp/PocketSharp.nuspec
+++ b/PocketSharp/PocketSharp.nuspec
@@ -10,7 +10,7 @@
     <projectUrl>http://pocketsharp.frontendplay.com</projectUrl>
     <iconUrl>http://pocketsharp.frontendplay.com/Assets/Images/pocketsharp.png</iconUrl>
     <requireLicenseAcceptance>false</requireLicenseAcceptance>
-    <description>$description$</description>
+    <description>PocketSharp is a .NET class library, that integrates the Pocket API v3</description>
     <language>en-US</language>
     <releaseNotes>
       <![CDATA[
diff --git a/PocketSharp/Properties/AssemblyInfo.cs b/PocketSharp/Properties/AssemblyInfo.cs
index 53e5423..66c2250 100644
--- a/PocketSharp/Properties/AssemblyInfo.cs
+++ b/PocketSharp/Properties/AssemblyInfo.cs
@@ -25,5 +25,5 @@ using System.Runtime.InteropServices;
 // You can specify all the values or you can default the Build and Revision Numbers
 // by using the '*' as shown below:
 // [assembly: AssemblyVersion("1.0.*")]
-[assembly: AssemblyVersion("1.0.0")]
-[assembly: AssemblyFileVersion("1.0.0")]
\ No newline at end of file
+[assembly: AssemblyVersion("1.2.0")]
+[assembly: AssemblyFileVersion("1.2.0")]
\ No newline at end of file
diff --git a/README.md b/README.md
index 2cea6db..9f4caf6 100644
--- a/README.md
+++ b/README.md
@@ -19,7 +19,7 @@ PocketSharp is a **Portable Class Library** (since 1.0.0), therefore it's compat
 - **Windows Phone** >= 7.5
 - **Windows Store**
 
-You can find examples for Silverlight 5, WP8 and WPF in the `PocketSharp.Examples` folder.
+You can find examples for Silverlight 5, WP8 and WPF in the `PocketSharp.Examples` ([@github](https://github.com/ceee/PocketSharp/tree/master/PocketSharp.Examples)) folder.
 
 ## Async Support
 
@@ -142,7 +142,30 @@ Get list of all items:
 
 ```csharp
 List<PocketItem> items = await _client.Retrieve();
-// equivalent to: await _client.Retrieve(RetrieveFilter.All)
+// equivalent to: await _client.RetrieveByFilter(RetrieveFilter.All)
+```
+
+Get a list with specific parameters (explanation in the [Pocket Docs](http://getpocket.com/developer/docs/v3/retrieve)):
+
+```csharp
+List<PocketItem> items = await _client.Retrieve(
+  State? state = null,
+  bool? favorite = null,
+  string tag = null,
+  ContentType? contentType = null,
+  Sort? sort = null,
+  string search = null,
+  string domain = null,
+  DateTime? since = null,
+  int? count = null,
+  int? offset = null 
+);
+```
+
+It's best to use parameters as _named parameters_, to avoid typing `null` values:
+
+```csharp
+List<PocketItem> items = await _client.Retrieve(count: 10, offset: 20, sort: Sort.oldest);
 ```
 
 Find items by a tag:
@@ -157,10 +180,11 @@ Find items by a search string:
 List<PocketItem> items = await _client.Search("css");
 ```
 
-Find items by a filter:
+Get a filtered list:
 
 ```csharp
-List<PocketItem> items = await _client.Retrieve(RetrieveFilter.Favorite); // only favorites
+List<PocketItem> items = await _client.RetrieveByFilter(RetrieveFilter.Favorite);
+// returns favorites only
 ```
 
 The RetrieveFilter Enum is specified as follows:
@@ -169,22 +193,6 @@ The RetrieveFilter Enum is specified as follows:
 enum RetrieveFilter { All, Unread, Archive, Favorite, Article, Video, Image }
 ```
 
-#### Custom Parameters
-
-You can create a completely custom parameter list for retrieval with the POCO `RetrieveParameters`:
-
-```csharp
-var parameters = new RetrieveParameters()
-{
-	Count = 50,
-	Offset = 100,
-	Sort = Sort.oldest
-	...
-};
-
-List<PocketItem> items = await _client.Retrieve(parameters);
-```
-
 ## Add
 
 Adds a new item to your pocket list.
@@ -257,6 +265,8 @@ Renames a tag for the specified item:
 
 ## Release History
 
+- 2013-09-17 v1.2.0 simplified retrieve methods
+- 2013-09-17 v1.1.0 fix modification requests
 - 2013-09-15 v1.0.0 convert to PCL & implement async
 - 2013-08-16 v0.3.2 tag modification fixed and full retrieval of items for Retrieve method
 - 2013-07-07 v0.3.1 authentication fixes