From cc5bc61aceb690b80ff21dc83ae7a4963401d829 Mon Sep 17 00:00:00 2001
From: Tobias Klika <cee@live.at>
Date: Fri, 3 Apr 2015 22:01:07 +0200
Subject: [PATCH] add comments

---
 src/OnePeek.Api/AppMetadataEndpoint.cs        | 20 +++++++++++++++++++
 src/OnePeek.Api/AppRatingEndpoint.cs          |  8 ++++++++
 src/OnePeek.Api/Configuration.cs              |  7 +++++++
 .../Extensions/EntityExtensions.cs            | 10 ++++++----
 4 files changed, 41 insertions(+), 4 deletions(-)

diff --git a/src/OnePeek.Api/AppMetadataEndpoint.cs b/src/OnePeek.Api/AppMetadataEndpoint.cs
index b156fff..62c4d7e 100644
--- a/src/OnePeek.Api/AppMetadataEndpoint.cs
+++ b/src/OnePeek.Api/AppMetadataEndpoint.cs
@@ -7,11 +7,19 @@ using System.Threading.Tasks;
 using System.Xml.Linq;
 using System.Linq;
 using System.Collections.Generic;
+using System.Diagnostics;
 
 namespace OnePeek.Api
 {
   public class AppMetadataEndpoint : ApiBase
   {
+    /// <summary>
+    /// Get app description, images, publisher, rating and more for an app in the specified culture.
+    /// </summary>
+    /// <param name="appId">The ID of the app. Can be found in the dev portal or the store URI.</param>
+    /// <param name="store">The store where the app is published.</param>
+    /// <param name="storeCulture">Culture of the query (returns location specific metadata + ratings).</param>
+    /// <returns></returns>
     public async Task<AppMetadata> GetMetadata(string appId, StoreType store, StoreCultureType storeCulture)
     {
       if (storeCulture == StoreCultureType.Unknown)
@@ -61,6 +69,12 @@ namespace OnePeek.Api
 
 
 
+    /// <summary>
+    /// Creates an URI from an image urn (included in the AppImage POCO).
+    /// </summary>
+    /// <param name="urn">The urn (is part of the AppImage).</param>
+    /// <param name="imageType">Crops the image accordingly.</param>
+    /// <returns></returns>
     public Uri GetImageUri(string urn, StoreImageType imageType = StoreImageType.None)
     {
       string type = imageType.GetEnumDisplayName();
@@ -69,6 +83,12 @@ namespace OnePeek.Api
 
 
 
+    /// <summary>
+    /// Returns a stream for a store image.
+    /// </summary>
+    /// <param name="urn">The urn (is part of the AppImage).</param>
+    /// <param name="imageType">Crops the image accordingly.</param>
+    /// <returns></returns>
     public async Task<Stream> GetImageAsStream(string urn, StoreImageType imageType = StoreImageType.None)
     {
       string type = imageType.GetEnumDisplayName();
diff --git a/src/OnePeek.Api/AppRatingEndpoint.cs b/src/OnePeek.Api/AppRatingEndpoint.cs
index c4d8041..f26c2ef 100644
--- a/src/OnePeek.Api/AppRatingEndpoint.cs
+++ b/src/OnePeek.Api/AppRatingEndpoint.cs
@@ -10,6 +10,14 @@ namespace OnePeek.Api
 {
   public class AppRatingEndpoint : ApiBase
   {
+    /// <summary>
+    /// Get a list of reviews (up to 20 per request) for the specified app.
+    /// </summary>
+    /// <param name="appId">The ID of the app. Can be found in the dev portal or the store URI.</param>
+    /// <param name="store">The store where the app is published.</param>
+    /// <param name="storeCulture">Culture of the query (returns location specific metadata + ratings).</param>
+    /// <param name="sorting">Sorting criteria.</param>
+    /// <returns></returns>
     public async Task<AppReviews> GetReviews(string appId, StoreType store, StoreCultureType storeCulture, StoreReviewSorting sorting)
     {
       if (storeCulture == StoreCultureType.Unknown)
diff --git a/src/OnePeek.Api/Configuration.cs b/src/OnePeek.Api/Configuration.cs
index 40817f5..36b12c8 100644
--- a/src/OnePeek.Api/Configuration.cs
+++ b/src/OnePeek.Api/Configuration.cs
@@ -1,7 +1,14 @@
 namespace OnePeek.Api
 {
+  /// <summary>
+  /// Coniguration options for the API
+  /// </summary>
   public static class Configuration
   {
+    /// <summary>
+    /// Ratings are returned on a 1-10 scale by default.
+    /// This changes it to a 1-5 scale, which is more suited for displaying it as stars.
+    /// </summary>
     public static bool UseFiveStarSystem = false;
   }
 }
diff --git a/src/OnePeek.Api/Extensions/EntityExtensions.cs b/src/OnePeek.Api/Extensions/EntityExtensions.cs
index 5ce8c3b..d7b2b72 100644
--- a/src/OnePeek.Api/Extensions/EntityExtensions.cs
+++ b/src/OnePeek.Api/Extensions/EntityExtensions.cs
@@ -1,14 +1,16 @@
 using OnePeek.Entities;
 using System;
-using System.Collections.Generic;
-using System.Linq;
-using System.Text;
-using System.Threading.Tasks;
 
 namespace OnePeek.Api.Extensions
 {
   public static class EntityExtensions
   {
+    /// <summary>
+    /// Creates an URI from an image.
+    /// </summary>
+    /// <param name="appImage">The appImage is returned as part of API endpoint requests.</param>
+    /// <param name="imageType">Crops the image accordingly.</param>
+    /// <returns></returns>
     public static Uri GetUri(this AppImage appImage, StoreImageType imageType = StoreImageType.None)
     {
       return EndpointUris.GetWindowsPhoneImageUri(appImage.Urn, imageType.GetEnumDisplayName());