Updated documentation and polish for the new OS-KSCATALOG operations

Author: sharwell

src/Documentation/SharedTokens.tokens

@@ -27,6 +27,13 @@
     </para>
   </item>
 
+  <item id="NullIfNotIncluded">
+    <para>-or-</para>
+    <para>
+      <see langword="null"/> if the underlying property was not included in the JSON representation of the object.
+    </para>
+  </item>
+
   <!--
     The following items can only be used in <token> elements that appear in **MAML topics**.
   -->

src/corelib/Core/Domain/EndpointTemplate.cs

@@ -5,34 +5,60 @@
     using Newtonsoft.Json;
 
     /// <summary>
-    /// A personality that a user assumes when performing a specific set of operations. A role
-    /// includes a set of right and privileges. A user assuming that role inherits those rights
-    /// and privileges.
+    /// This class models the JSON representation of an endpoint template resource in the OpenStack Identity Service V2.
     /// </summary>
     /// <remarks>
-    /// In OpenStack Identity Service, a token that is issued to a user includes the list of
-    /// roles that user can assume. Services that are being called by that user determine how
-    /// they interpret the set of roles a user has and to which operations or resources each
-    /// role grants access.
+    /// <para>This object is part of the <c>OS-KSCATALOG</c> extension to the OpenStack Identity Service V2.</para>
     /// </remarks>
+    /// <seealso href="http://developer.openstack.org/api-ref-identity-v2.html#os-kscatalog-ext">OS-KSCATALOG admin extension (Identity API v2.0 - OpenStack Complete API Reference)</seealso>
     /// <threadsafety static="true" instance="false"/>
+    /// <preliminary/>
     [JsonObject(MemberSerialization.OptIn)]
     [DebuggerDisplay("{Id, nq}")]
-    public class EndpointTemplate
+    public class EndpointTemplate : ExtensibleJsonObject
     {
         /// <summary>
-        /// Gets the unique identifier for the Endpoint Template.
+        /// This is the backing field for the <see cref="Id"/> property.
         /// </summary>
-        [JsonProperty("id")]
-        public string Id { get; private set; }
+        [JsonProperty("id", DefaultValueHandling = DefaultValueHandling.Ignore)]
+        private EndpointTemplateId _id;
 
-        public EndpointTemplate(string id)
+        /// <summary>
+        /// Initializes a new instance of the <see cref="EndpointTemplate"/> class
+        /// during JSON deserialization.
+        /// </summary>
+        [JsonConstructor]
+        protected EndpointTemplate()
+        {
+        }
+
+        /// <summary>
+        /// Initializes a new instance of the <see cref="EndpointTemplate"/> class with the specified endpoint template
+        /// identifier.
+        /// </summary>
+        /// <param name="id">The unique identifier of the endpoint template.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="id"/> is <see langword="null"/>.</exception>
+        public EndpointTemplate(EndpointTemplateId id)
         {
             if (id == null)
                 throw new ArgumentNullException("id");
 
-            Id = id;
+            _id = id;
+        }
+
+        /// <summary>
+        /// Gets the unique identifier for the endpoint template.
+        /// </summary>
+        /// <value>
+        /// <para>The unique identifier for the endpoint template.</para>
+        /// <token>NullIfNotIncluded</token>
+        /// </value>
+        public EndpointTemplateId Id
+        {
+            get
+            {
+                return _id;
+            }
         }
     }
 }
-

src/corelib/Core/Domain/EndpointTemplateId.cs

@@ -0,0 +1,45 @@
+namespace net.openstack.Core.Domain
+{
+    using System;
+    using net.openstack.Core;
+    using Newtonsoft.Json;
+
+    /// <summary>
+    /// Represents the unique identifier of an <see cref="EndpointTemplate"/>.
+    /// </summary>
+    /// <remarks>
+    /// <para>This object is part of the <c>OS-KSCATALOG</c> extension to the OpenStack Identity Service V2.</para>
+    /// </remarks>
+    /// <seealso cref="EndpointTemplate.Id"/>
+    /// <threadsafety static="true" instance="false"/>
+    /// <preliminary/>
+    [JsonConverter(typeof(EndpointTemplateId.Converter))]
+    public sealed class EndpointTemplateId : ResourceIdentifier<EndpointTemplateId>
+    {
+        /// <summary>
+        /// Initializes a new instance of the <see cref="EndpointTemplateId"/> class
+        /// with the specified identifier value.
+        /// </summary>
+        /// <param name="id">The identifier value.</param>
+        /// <exception cref="ArgumentNullException">If <paramref name="id"/> is <see langword="null"/>.</exception>
+        /// <exception cref="ArgumentException">If <paramref name="id"/> is empty.</exception>
+        public EndpointTemplateId(string id)
+            : base(id)
+        {
+        }
+
+        /// <summary>
+        /// Provides support for serializing and deserializing <see cref="EndpointTemplateId"/>
+        /// objects to JSON string values.
+        /// </summary>
+        /// <threadsafety static="true" instance="false"/>
+        private sealed class Converter : ConverterBase
+        {
+            /// <inheritdoc/>
+            protected override EndpointTemplateId FromValue(string id)
+            {
+                return new EndpointTemplateId(id);
+            }
+        }
+    }
+}