Additional code documentation

GM.Api/GMClientBase.cs

@@ -30,7 +30,12 @@ namespace GM.Api
 
         HttpClient _client;
 
+        /// <summary>
+        /// If the current login token has been upgraded
+        /// Note: it is not known how long this lasts
+        /// </summary>
         public bool IsUpgraded { get; private set; } = false;
+
         bool _isConnected = false;
 
         /// <summary>
@@ -457,7 +462,12 @@ namespace GM.Api
             }
         }
 
-
+        /// <summary>
+        /// Initiate a command and wait for completion, returning the Command Response
+        /// </summary>
+        /// <param name="command">Command Name</param>
+        /// <param name="requestParameters">Command request parameters</param>
+        /// <returns>Command Response</returns>
         protected async Task<CommandResponse> InitiateCommandAndWait(string command, JObject requestParameters)
         {
             var result = await InitiateCommand(command, requestParameters);
@@ -465,6 +475,13 @@ namespace GM.Api
             return endStatus;
         }
 
+
+        /// <summary>
+        /// Initiate a command and wait for completion, parsing the response for success flag
+        /// </summary>
+        /// <param name="command">Command Name</param>
+        /// <param name="requestParameters">Command request parameters</param>
+        /// <returns>True or false if the command succeeded</returns>
         protected async Task<bool> InitiateCommandAndWaitForSuccess(string command, JObject requestParameters)
         {
             var result = await InitiateCommandAndWait(command, requestParameters);
@@ -479,7 +496,11 @@ namespace GM.Api
             }
         }
 
-
+        /// <summary>
+        /// Call the status URL for a command
+        /// </summary>
+        /// <param name="statusUrl"></param>
+        /// <returns></returns>
         async Task<CommandResponse> PollCommandStatus(string statusUrl)
         {
             var response = await GetAsync($"{statusUrl}?units=METRIC");
@@ -496,6 +517,11 @@ namespace GM.Api
         }
 
 
+        /// <summary>
+        /// Get the list of vehicle configurations for the first 10 vehicles on the account
+        /// Result of this request is required to use vehicle-specific commands
+        /// </summary>
+        /// <returns>Collection of Vehicle configurations</returns>
         public async Task<IEnumerable<Vehicle>> GetVehicles()
         {
             //these could be parameterized, but we better stick with what the app does

GM.Api/GenericGMClient.cs

@@ -8,7 +8,7 @@ using System.Threading.Tasks;
 namespace GM.Api
 {
     /// <summary>
-    /// Generic implementation of GM Client supporting a limited set of commands or manually defined commands
+    /// Generic implementation of GM Client supporting a limited set of commands
     /// </summary>
     public class GenericGMClient : GMClientBase
     {
@@ -16,7 +16,10 @@ namespace GM.Api
         {
         }
 
-
+        /// <summary>
+        /// Retrieve Diagnostic data for the active vehicle
+        /// </summary>
+        /// <returns></returns>
         public async Task<DiagnosticResponse[]> GetDiagnostics()
         {
             var cmdInfo = ActiveVehicle.GetCommand("diagnostics");
@@ -39,14 +42,23 @@ namespace GM.Api
         }
 
 
-
+        /// <summary>
+        /// Issue an arbitrary command
+        /// </summary>
+        /// <param name="commandName">Name of the command. Must exists in the vehicle's configuration</param>
+        /// <param name="parameters">JSON parameters for the command</param>
+        /// <returns></returns>
         public async Task<CommandResponse> IssueCommand(string commandName, JObject parameters = null)
         {
             return await InitiateCommandAndWait(commandName, parameters);
         }
 
-
-        public async Task<bool> LockDoor(string pin)
+        /// <summary>
+        /// Lock the active vehicles's doors and wait for completion
+        /// Privileged Command
+        /// </summary>
+        /// <returns>True or false for success</returns>
+        public async Task<bool> LockDoor()
         {
             var reqObj = new JObject()
             {
@@ -57,7 +69,12 @@ namespace GM.Api
             return await InitiateCommandAndWaitForSuccess("lockDoor", reqObj);
         }
 
-        public async Task<bool> UnlockDoor(string pin)
+        /// <summary>
+        /// Unlock the active vehicles's doors and wait for completion
+        /// Privileged Command
+        /// </summary>
+        /// <returns>True or false for success</returns>
+        public async Task<bool> UnlockDoor()
         {
 
             var reqObj = new JObject()
@@ -68,18 +85,33 @@ namespace GM.Api
             return await InitiateCommandAndWaitForSuccess("unlockDoor", reqObj);
         }
 
-        public async Task<bool> Start(string pin)
+        /// <summary>
+        /// Remote start the active vehicle and wait for completion
+        /// Privileged Command
+        /// </summary>
+        /// <returns>True or false for success</returns>
+        public async Task<bool> Start()
         {
             return await InitiateCommandAndWaitForSuccess("start", null);
         }
 
-        public async Task<bool> CancelStart(string pin)
+        /// <summary>
+        /// Remote stop the active vehicle and wait for completion
+        /// Privileged Command
+        /// </summary>
+        /// <returns>True or false for success</returns>
+        public async Task<bool> CancelStart()
         {
             return await InitiateCommandAndWaitForSuccess("cancelStart", null);
         }
 
 
-        public async Task<bool> Alert(string pin)
+        /// <summary>
+        /// Set off remote alarm on the active vehicle and wait for completion
+        /// Privileged Command
+        /// </summary>
+        /// <returns>True or false for success</returns>
+        public async Task<bool> Alert()
         {
             var reqObj = new JObject()
             {
@@ -93,8 +125,12 @@ namespace GM.Api
             return await InitiateCommandAndWaitForSuccess("alert", reqObj);
         }
 
-
-        public async Task<bool> CancelAlert(string pin)
+        /// <summary>
+        /// Stop remote alarm on the active vehicle and wait for completion
+        /// Privileged Command
+        /// </summary>
+        /// <returns>True or false for success</returns>
+        public async Task<bool> CancelAlert()
         {
             return await InitiateCommandAndWaitForSuccess("cancelAlert", null);
         }

GM.Api/Tokens/LoginData.cs

@@ -10,24 +10,46 @@ namespace GM.Api.Tokens
     /// </summary>
     public class LoginData
     {
+        /// <summary>
+        /// Access token used as bearer token
+        /// </summary>
         [JsonProperty("access_token")]
         public string AccessToken { get; set; }
 
+        /// <summary>
+        /// Bearer
+        /// </summary>
         [JsonProperty("token_type")]
         public string TokenType { get; set; }
 
+        /// <summary>
+        /// Token expiration in seconds
+        /// (Note: I have seen the tokens expire quicker)
+        /// </summary>
         [JsonProperty("expires_in")]
         public int ExpiresIn { get; set; }
 
+        /// <summary>
+        /// List of scopes
+        /// </summary>
         [JsonProperty("scope")]
         public string Scope { get; set; }
 
+        /// <summary>
+        /// Information about the OnStar account
+        /// </summary>
         [JsonProperty("onstar_account_info")]
         public Onstar_Account_Info OnStarAccountInfo { get; set; }
 
+        /// <summary>
+        /// Information about the user
+        /// </summary>
         [JsonProperty("user_info")]
         public User_Info UserInfo { get; set; }
 
+        /// <summary>
+        /// RSA hashed itentity token (JWT) used in refresh assertion
+        /// </summary>
         [JsonProperty("id_token")]
         public string IdToken { get; set; }
 

GM.Api/Tokens/LoginRequest.cs

@@ -9,21 +9,39 @@ using System.Text;
 namespace GM.Api.Tokens
 {
 
-
+    /// <summary>
+    /// Body that is encoded into the login and upgrade JWT
+    /// </summary>
     public class LoginRequest
     {
+        /// <summary>
+        /// Client ID from configuration
+        /// </summary>
         [JsonProperty("client_id", DefaultValueHandling = DefaultValueHandling.Ignore)]
         public string ClientId { get; set; }
 
+        /// <summary>
+        /// A GUID represented as a string, specific to the device
+        /// (randomly generated once and saved)
+        /// </summary>
         [JsonProperty("device_id", DefaultValueHandling = DefaultValueHandling.Ignore)]
         public string DeviceId { get; set; }
 
+        /// <summary>
+        /// OAuth grant type
+        /// </summary>
         [JsonProperty("grant_type", DefaultValueHandling = DefaultValueHandling.Ignore)]
         public string GrantType { get; set; }
 
+        /// <summary>
+        /// Random string generated by a specifi method
+        /// </summary>
         [JsonProperty("nonce", DefaultValueHandling = DefaultValueHandling.Ignore)]
         public string Nonce { get; set; }
 
+        /// <summary>
+        /// User's password
+        /// </summary>
         [JsonProperty("password", DefaultValueHandling = DefaultValueHandling.Ignore)]
         public string Password { get; set; }
 
@@ -40,6 +58,9 @@ namespace GM.Api.Tokens
         [JsonProperty("timestamp", DefaultValueHandling = DefaultValueHandling.Ignore)]
         public string Timestamp { get; set; }
 
+        /// <summary>
+        /// Username for GM account
+        /// </summary>
         [JsonProperty("username", DefaultValueHandling = DefaultValueHandling.Ignore)]
         public string Username { get; set; }
 
@@ -51,7 +72,7 @@ namespace GM.Api.Tokens
         public string Credential { get; set; }
 
         /// <summary>
-        /// "PIN" for onstanr pin
+        /// "PIN" for onstar pin
         /// </summary>
         [JsonProperty("credential_type", DefaultValueHandling = DefaultValueHandling.Ignore)]
         public string CredentialType { get; set; }