From f8eaf47f8071a9da767a3b44d16698b02a79cd9f Mon Sep 17 00:00:00 2001 From: ceee Date: Sat, 21 Sep 2013 00:06:56 +0200 Subject: [PATCH] update method documentation --- PocketSharp/Components/Add.cs | 6 ++-- PocketSharp/Components/Authentification.cs | 23 +++++++++----- PocketSharp/Components/Modify.cs | 9 ++++++ PocketSharp/Components/ModifyTags.cs | 36 ++++++++++++++-------- PocketSharp/Components/Retrieve.cs | 15 ++++++--- 5 files changed, 63 insertions(+), 26 deletions(-) diff --git a/PocketSharp/Components/Add.cs b/PocketSharp/Components/Add.cs index b366956..c61962c 100644 --- a/PocketSharp/Components/Add.cs +++ b/PocketSharp/Components/Add.cs @@ -16,7 +16,8 @@ namespace PocketSharp /// A comma-separated list of tags to apply to the item /// This can be included for cases where an item does not have a title, which is typical for image or PDF URLs. If Pocket detects a title from the content of the page, this parameter will be ignored. /// If you are adding Pocket support to a Twitter client, please send along a reference to the tweet status id. This allows Pocket to show the original tweet alongside the article. - /// + /// A simple representation of the saved item which doesn't contain all data (is only returned by calling the Retrieve method) + /// public async Task Add(Uri uri, string[] tags = null, string title = null, string tweetID = null) { AddParameters parameters = new AddParameters() @@ -37,7 +38,8 @@ namespace PocketSharp /// Adds a new item to pocket /// /// The URL of the item you want to save - /// + /// A simple representation of the saved item which doesn't contain all data (is only returned by calling the Retrieve method) + /// public async Task Add(Uri uri) { return await Add(uri, null); diff --git a/PocketSharp/Components/Authentification.cs b/PocketSharp/Components/Authentification.cs index b619737..15855a2 100644 --- a/PocketSharp/Components/Authentification.cs +++ b/PocketSharp/Components/Authentification.cs @@ -11,15 +11,17 @@ namespace PocketSharp public partial class PocketClient { /// - /// Retrieves the requestCode from Pocket. + /// Retrieves the requestCode from Pocket, which is used to generate the Authentication URI to authenticate the user /// /// + /// Authentication methods need a callbackUri on initialization of the PocketClient class + /// public async Task GetRequestCode() { // check if request code is available if (CallbackUri == null) { - throw new PocketException("Authentication methods need a callbackUri on initialization of the PocketClient class"); + throw new NullReferenceException("Authentication methods need a callbackUri on initialization of the PocketClient class"); } // do request @@ -39,14 +41,15 @@ namespace PocketSharp /// /// Generate Authentication URI from requestCode /// - /// The requestCode. - /// + /// The requestCode. If no requestCode is supplied, the property from the PocketClient intialization is used. + /// A valid URI to redirect the user to. + /// Call GetRequestCode() first to receive a request_code public Uri GenerateAuthenticationUri(string requestCode = null) { // check if request code is available if(RequestCode == null && requestCode == null) { - throw new PocketException("Call GetRequestCode() first to receive a request_code"); + throw new NullReferenceException("Call GetRequestCode() first to receive a request_code"); } // override property with given param if available @@ -60,15 +63,19 @@ namespace PocketSharp /// - /// Requests the access code after authentification + /// Requests the access code after authentication + /// The access code has to permanently be stored within the users session, and should be added as a parameter for all future PocketClient initializations. /// - /// + /// The requestCode. If no requestCode is supplied, the property from the PocketClient intialization is used. + /// The permanent access code, which is used to authenticate the user with the application + /// Call GetRequestCode() first to receive a request_code + /// public async Task GetAccessCode(string requestCode = null) { // check if request code is available if(RequestCode == null && requestCode == null) { - throw new PocketException("Call GetRequestCode() first to receive a request_code"); + throw new NullReferenceException("Call GetRequestCode() first to receive a request_code"); } // override property with given param if available diff --git a/PocketSharp/Components/Modify.cs b/PocketSharp/Components/Modify.cs index e94c7ca..f902c89 100644 --- a/PocketSharp/Components/Modify.cs +++ b/PocketSharp/Components/Modify.cs @@ -14,6 +14,7 @@ namespace PocketSharp /// /// The item ID. /// + /// public async Task Archive(int itemID) { return await SendDefault(itemID, "archive"); @@ -25,6 +26,7 @@ namespace PocketSharp /// /// The item. /// + /// public async Task Archive(PocketItem item) { return await Archive(item.ID); @@ -36,6 +38,7 @@ namespace PocketSharp /// /// The item ID. /// + /// public async Task Unarchive(int itemID) { return await SendDefault(itemID, "readd"); @@ -47,6 +50,7 @@ namespace PocketSharp /// /// The item. /// + /// public async Task Unarchive(PocketItem item) { return await Unarchive(item.ID); @@ -58,6 +62,7 @@ namespace PocketSharp /// /// The item ID. /// + /// public async Task Favorite(int itemID) { return await SendDefault(itemID, "favorite"); @@ -69,6 +74,7 @@ namespace PocketSharp /// /// The item. /// + /// public async Task Favorite(PocketItem item) { return await Favorite(item.ID); @@ -80,6 +86,7 @@ namespace PocketSharp /// /// The item ID. /// + /// public async Task Unfavorite(int itemID) { return await SendDefault(itemID, "unfavorite"); @@ -91,6 +98,7 @@ namespace PocketSharp /// /// The item. /// + /// public async Task Unfavorite(PocketItem item) { return await Unfavorite(item.ID); @@ -102,6 +110,7 @@ namespace PocketSharp /// /// The item ID. /// + /// public async Task Delete(int itemID) { return await SendDefault(itemID, "delete"); diff --git a/PocketSharp/Components/ModifyTags.cs b/PocketSharp/Components/ModifyTags.cs index 386aa74..0429e21 100644 --- a/PocketSharp/Components/ModifyTags.cs +++ b/PocketSharp/Components/ModifyTags.cs @@ -9,11 +9,12 @@ namespace PocketSharp public partial class PocketClient { /// - /// Adds the specified tags. + /// Adds the specified tags to an item. /// /// The item ID. /// The tags. /// + /// public async Task AddTags(int itemID, string[] tags) { return await SendTags(itemID, "tags_add", tags); @@ -21,11 +22,12 @@ namespace PocketSharp /// - /// Adds the specified tags. + /// Adds the specified tags to an item. /// /// The item. /// The tags. /// + /// public async Task AddTags(PocketItem item, string[] tags) { return await AddTags(item.ID, tags); @@ -33,11 +35,12 @@ namespace PocketSharp /// - /// Removes the specified tags. + /// Removes the specified tags from an item. /// /// The item ID. /// The tags. /// + /// public async Task RemoveTags(int itemID, string[] tags) { return await SendTags(itemID, "tags_remove", tags); @@ -45,11 +48,12 @@ namespace PocketSharp /// - /// Removes the specified tags. + /// Removes the specified tags from an item. /// /// The item. /// The tag. /// + /// public async Task RemoveTags(PocketItem item, string[] tags) { return await RemoveTags(item.ID, tags); @@ -57,11 +61,12 @@ namespace PocketSharp /// - /// Removes a tag. + /// Removes a tag from an item. /// /// The item ID. /// The tag. /// + /// public async Task RemoveTag(int itemID, string tag) { return await SendTags(itemID, "tags_remove", new string[] { tag }); @@ -69,11 +74,12 @@ namespace PocketSharp /// - /// Removes a tag. + /// Removes a tag from an item. /// /// The item. /// The tags. /// + /// public async Task RemoveTag(PocketItem item, string tag) { return await RemoveTag(item.ID, tag); @@ -81,10 +87,11 @@ namespace PocketSharp /// - /// Clears all tags. + /// Clears all tags from an item. /// /// The item ID. /// + /// public async Task RemoveTags(int itemID) { return await SendDefault(itemID, "tags_clear"); @@ -92,10 +99,11 @@ namespace PocketSharp /// - /// Clears all tags. + /// Clears all tags from an item. /// /// The item. /// + /// public async Task RemoveTags(PocketItem item) { return await RemoveTags(item.ID); @@ -103,11 +111,12 @@ namespace PocketSharp /// - /// Replaces all existing tags with the given tags. + /// Replaces all existing tags with the given tags in an item. /// /// The item ID. /// The tags. /// + /// public async Task ReplaceTags(int itemID, string[] tags) { return await SendTags(itemID, "tags_replace", tags); @@ -115,11 +124,12 @@ namespace PocketSharp /// - /// Replaces all existing tags with new ones. + /// Replaces all existing tags with the given new ones in an item. /// /// The item. /// The tags. /// + /// public async Task ReplaceTags(PocketItem item, string[] tags) { return await ReplaceTags(item.ID, tags); @@ -127,12 +137,13 @@ namespace PocketSharp /// - /// Renames a tag. + /// Renames a tag in an item. /// /// The item ID. /// The old tag. /// The new tag name. /// + /// public async Task RenameTag(int itemID, string oldTag, string newTag) { return await Send(new ActionParameter() @@ -146,12 +157,13 @@ namespace PocketSharp /// - /// Renames a tag. + /// Renames a tag in an item. /// /// The item. /// The old tag. /// The new tag name. /// + /// public async Task RenameTag(PocketItem item, string oldTag, string newTag) { return await RenameTag(item.ID, oldTag, newTag); diff --git a/PocketSharp/Components/Retrieve.cs b/PocketSharp/Components/Retrieve.cs index 041667f..974c29d 100644 --- a/PocketSharp/Components/Retrieve.cs +++ b/PocketSharp/Components/Retrieve.cs @@ -12,10 +12,12 @@ namespace PocketSharp public partial class PocketClient { /// - /// Retrieves all items from pocket + /// Retrieves items from pocket + /// with the given filters /// /// parameters, which are mapped to the officials from http://getpocket.com/developer/docs/v3/retrieve /// + /// public async Task> Retrieve( State? state = null, bool? favorite = null, @@ -52,9 +54,11 @@ namespace PocketSharp /// /// Retrieves an item by a given ID + /// Note: The Pocket API contains no method, which allows to retrieve a single item, so all items are retrieved and filtered locally by the ID. /// /// The item ID. /// + /// public async Task Retrieve(int itemID) { List items = await Retrieve( @@ -66,10 +70,11 @@ namespace PocketSharp /// - /// Retrieves all items with a filter from pocket + /// Retrieves all items by a given filter /// /// The filter. /// + /// public async Task> RetrieveByFilter(RetrieveFilter filter = RetrieveFilter.All) { RetrieveParameters parameters = new RetrieveParameters(); @@ -105,10 +110,11 @@ namespace PocketSharp /// - /// Retrieves items by tag from pocket + /// Retrieves items by tag /// /// The tag. /// + /// public async Task> SearchByTag(string tag) { return await Retrieve(tag: tag); @@ -116,10 +122,11 @@ namespace PocketSharp /// - /// Retrieves items from pocket which match the specified search string in title or content + /// Retrieves items which match the specified search string in title or content /// /// The search string. /// + /// public async Task> Search(string searchString) { return await Retrieve(search: searchString);