* Updated documentation.

RobThree · Jul 6, 2020 · 8d384a4 · 8d384a4
1 parent 1c5da5b
commit 8d384a4
Show file tree

Hide file tree

Showing 7 changed files with 97 additions and 18 deletions.
diff --git a/IdGen/ID.cs b/IdGen/ID.cs
@@ -5,7 +5,7 @@ namespace IdGen
     /// <summary>
     /// Holds information about a decoded id.
     /// </summary>
-    public struct ID : IEquatable<ID>
+    public struct Id : IEquatable<Id>
     {
         /// <summary>
         /// Gets the sequence number of the id.
@@ -23,13 +23,13 @@ public struct ID : IEquatable<ID>
         public DateTimeOffset DateTimeOffset { get; private set; }
 
         /// <summary>
-        /// Initializes a new instance of the <see cref="ID"/> struct.
+        /// Initializes a new instance of the <see cref="Id"/> struct.
         /// </summary>
         /// <param name="sequenceNumber">The sequence number of the id.</param>
         /// <param name="generatorId">The generator id of the generator that generated the id.</param>
         /// <param name="dateTimeOffset">The date/time when the id was generated.</param>
         /// <returns></returns>
-        internal ID(int sequenceNumber, int generatorId, DateTimeOffset dateTimeOffset)
+        internal Id(int sequenceNumber, int generatorId, DateTimeOffset dateTimeOffset)
         {
             SequenceNumber = sequenceNumber;
             GeneratorId = generatorId;
@@ -40,11 +40,11 @@ internal ID(int sequenceNumber, int generatorId, DateTimeOffset dateTimeOffset)
         /// Returns a value that indicates whether this instance is equal to a specified object.
         /// </summary>
         /// <param name="obj">The object to compare with this instance.</param>
-        /// <returns>true if <paramref name="obj"/> is a <see cref="ID"/> that has the same value as this instance; otherwise, false.</returns>
+        /// <returns>true if <paramref name="obj"/> is a <see cref="Id"/> that has the same value as this instance; otherwise, false.</returns>
         public override bool Equals(object obj)
         {
-            if (obj is ID)
-                return Equals((ID)obj);
+            if (obj is Id)
+                return Equals((Id)obj);
             return false;
         }
 
@@ -55,27 +55,27 @@ public override bool Equals(object obj)
         public override int GetHashCode() => Tuple.Create(DateTimeOffset, GeneratorId, SequenceNumber).GetHashCode();
 
         /// <summary>
-        /// Indicates whether the values of two specified <see cref="ID"/> objects are equal.
+        /// Indicates whether the values of two specified <see cref="Id"/> objects are equal.
         /// </summary>
         /// <param name="left">The first object to compare.</param>
         /// <param name="right">The second object to compare.</param>
         /// <returns>true if left and right are equal; otherwise, false.</returns>
-        public static bool operator ==(ID left, ID right) => left.Equals(right);
+        public static bool operator ==(Id left, Id right) => left.Equals(right);
 
         /// <summary>
-        /// Indicates whether the values of two specified <see cref="ID"/> objects are not equal.
+        /// Indicates whether the values of two specified <see cref="Id"/> objects are not equal.
         /// </summary>
         /// <param name="left">The first object to compare.</param>
         /// <param name="right">The second object to compare.</param>
         /// <returns>true if left and right are not equal; otherwise, false.</returns>
-        public static bool operator !=(ID left, ID right) => !(left == right);
+        public static bool operator !=(Id left, Id right) => !(left == right);
 
         /// <summary>
-        /// Returns a value indicating whether this instance and a specified <see cref="ID"/> object represent the same value.
+        /// Returns a value indicating whether this instance and a specified <see cref="Id"/> object represent the same value.
         /// </summary>
-        /// <param name="other">An <see cref="ID"/> to compare to this instance.</param>
+        /// <param name="other">An <see cref="Id"/> to compare to this instance.</param>
         /// <returns>true if <paramref name="other"/> is equal to this instance; otherwise, false.</returns>
-        public bool Equals(ID other) => GeneratorId == other.GeneratorId
+        public bool Equals(Id other) => GeneratorId == other.GeneratorId
                  && DateTimeOffset == other.DateTimeOffset
                  && SequenceNumber == other.SequenceNumber;
     }

diff --git a/IdGen/IdGenerator.cs b/IdGen/IdGenerator.cs
@@ -168,15 +168,15 @@ private long CreateIdImpl(out Exception? exception)
         /// based on the current <see cref="IdStructure"/> of the generator.
         /// </summary>
         /// <param name="id">The Id to extract information from.</param>
-        /// <returns>Returns an <see cref="ID" /> that contains information about the 'decoded' Id.</returns>
+        /// <returns>Returns an <see cref="IdGen.Id" /> that contains information about the 'decoded' Id.</returns>
         /// <remarks>
         /// IMPORTANT: note that this method relies on the <see cref="IdStructure"/> and timesource; if the id was
         /// generated with a diffferent IdStructure and/or timesource than the current one the 'decoded' ID will NOT
         /// contain correct information.
         /// </remarks>
-        public ID FromId(long id) =>
+        public Id FromId(long id) =>
             // Deconstruct Id by unshifting the bits into the proper parts
-            new ID(
+            new Id(
                 (int)(id & MASK_SEQUENCE),
                 (int)((id >> SHIFT_GENERATOR) & MASK_GENERATOR),
                 Options.TimeSource.Epoch.Add(TimeSpan.FromTicks(((id >> SHIFT_TIME) & MASK_TIME) * Options.TimeSource.TickDuration.Ticks))

diff --git a/IdGenDocumentation/Content/VersionHistory/v3.0.0.0.aml b/IdGenDocumentation/Content/VersionHistory/v3.0.0.0.aml
@@ -0,0 +1,53 @@
+<?xml version="1.0" encoding="utf-8"?>
+<topic id="61e6c82e-b332-46f3-8972-6b2d3aa77b53" revisionNumber="1">
+  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5" xmlns:xlink="http://www.w3.org/1999/xlink">
+    <introduction>
+      <para>
+        Version 3.0.0.0 was released on 2020-07-06.
+      </para>
+    </introduction>
+
+    <section>
+      <title>Changes in This Release</title>
+      <content>
+
+        <list class="bullet">
+          <listItem>
+            <para>
+              This release contains a few (minor) breaking changes. Generated 2.x ID's are still compatible with 3.x ID's. This release is mostly more, better and consistent naming of objects.
+            </para>
+
+            <list class="bullet">
+              <listItem>
+                <para>
+                  Most of the constructor overloads for the <codeEntityReference>T:IdGen.IdGenerator</codeEntityReference> have been replaced with a single constructor which accepts <codeEntityReference>T:IdGen.IdGeneratorOptions</codeEntityReference> that contains the <codeEntityReference>T:IdGen.ITimeSource</codeEntityReference>, <codeEntityReference>T:IdGen.IdStructure</codeEntityReference> and <codeEntityReference>T:IdGen.SequenceOverflowStrategy</codeEntityReference>.
+                </para>
+              </listItem>
+              <listItem>
+                <para>
+                  The <codeInline>MaskConfig</codeInline> class is now more appropriately named <codeEntityReference>T:IdGen.IdStructure</codeEntityReference> since it describes the structure of the generated ID's.
+                </para>
+              </listItem>
+              <listItem>
+                <para>
+                  The <codeInline>UseSpinWait</codeInline> property has moved to the <codeEntityReference>T:IdGen.IdGeneratorOptions</codeEntityReference> and is now an enum of type <codeEntityReference>T:IdGen.SequenceOverflowStrategy</codeEntityReference> instead of a boolean value. Note that this property has also been renamed in the config file (from <codeInline>useSpinWait</codeInline> to <codeInline>sequenceOverflowStrategy</codeInline>) and is no longer a boolean but rquires one of the values from <codeEntityReference>T:IdGen.SequenceOverflowStrategy</codeEntityReference>.
+                </para>
+              </listItem>
+              <listItem>
+                <para>
+                  <codeInline>ID</codeInline> is now <codeInline>Id</codeInline> (only used as return value by the <codeEntityReference>M:IdGen.IdGenerator.FromId(System.Int64)</codeEntityReference> method)
+                </para>
+              </listItem>
+            </list>
+
+          </listItem>
+        </list>
+      </content>
+    </section>
+
+    <relatedTopics>
+      <link xlink:href="4491ec46-0001-46c1-88b7-3dd2ee8472f3" />
+    </relatedTopics>
+
+  </developerConceptualDocument>
+</topic>
diff --git a/IdGenDocumentation/Content/Welcome.aml b/IdGenDocumentation/Content/Welcome.aml
@@ -237,7 +237,16 @@
           <![CDATA[
           var generator = AppConfigFactory.GetFromConfig("foo");
           ]]>
-        </code>        
+        </code>
+      </content>
+    </section>
+
+    <section>
+      <title>Upgrading from 2.x to 3.x</title>
+      <content>
+        <para>
+          Upgrading from 2.x to 3.x should be pretty straightforward. See <link xlink:href="61e6c82e-b332-46f3-8972-6b2d3aa77b53" /> for the changes.
+        </para>
       </content>
     </section>
 

diff --git a/IdGenDocumentation/ContentLayout.content b/IdGenDocumentation/ContentLayout.content
@@ -59,7 +59,7 @@
         <HelpKeyword index="K" term="version, 2.3.0.0" />
       </HelpKeywords>
     </Topic>
-    <Topic id="006fa4ee-5895-4401-873a-006b4316365d" visible="True" isSelected="true" title="Version 2.4.0.0">
+    <Topic id="006fa4ee-5895-4401-873a-006b4316365d" visible="True" title="Version 2.4.0.0">
       <HelpKeywords>
         <HelpKeyword index="K" term="version, 2.4.0.0" />
       </HelpKeywords>
@@ -69,5 +69,10 @@
         <HelpKeyword index="K" term="version, 2.4.1.0" />
       </HelpKeywords>
     </Topic>
+    <Topic id="61e6c82e-b332-46f3-8972-6b2d3aa77b53" visible="True" isSelected="true" title="Version 3.0.0.0">
+      <HelpKeywords>
+        <HelpKeyword index="K" term="version, 3.0.0.0" />
+      </HelpKeywords>
+    </Topic>
   </Topic>
 </Topics>
diff --git a/IdGenDocumentation/IdGenDocumentation.shfbproj b/IdGenDocumentation/IdGenDocumentation.shfbproj
@@ -108,6 +108,7 @@
     <None Include="Content\VersionHistory\v2.3.0.0.aml" />
     <None Include="Content\VersionHistory\v2.4.0.0.aml" />
     <None Include="Content\VersionHistory\v2.4.1.0.aml" />
+    <None Include="Content\VersionHistory\v3.0.0.0.aml" />
     <None Include="Content\VersionHistory\VersionHistory.aml" />
     <None Include="Content\Welcome.aml" />
   </ItemGroup>

diff --git a/README.md b/README.md
@@ -146,6 +146,17 @@ You can get the IdGenerator from the config using the following code:
 
 `var generator = AppConfigFactory.GetFromConfig("foo");`
 
+## Upgrading from 2.x to 3.x
+
+Upgrading from 2.x to 3.x should be pretty straightforward. The following things have changed:
+
+* Most of the constructor overloads for the `IdGenerator` have been replaced with a single constructor which accepts `IdGeneratorOptions` that contains the `ITimeSource`, `IdStructure` and `SequenceOverflowStrategy`
+* The `MaskConfig` class is now more appropriately named `IdStructure` since it describes the structure of the generated ID's.
+* The `UseSpinWait` property has moved to the `IdGeneratorOptions` and is now an enum of type `SequenceOverflowStrategy` instead of a boolean value. Note that this property has also been renamed in the config file (from `useSpinWait` to `sequenceOverflowStrategy`) and is no longer a boolean but rquires one of the values from `SequenceOverflowStrategy`.
+* `ID` is now `Id` (only used as return value by the `FromId()` method)
+
+The generated 2.x ID's are still compatible with 3.x ID's. This release is mostly more, better and consistent naming of objects.
+
 <hr>
 
 Icon made by [Freepik](http://www.flaticon.com/authors/freepik) from [www.flaticon.com](http://www.flaticon.com) is licensed by [CC 3.0](http://creativecommons.org/licenses/by/3.0/).