Merge pull request #9 from kesac/dev-documentation-updates

Inline documentation updates

.gitignore

@@ -28,3 +28,4 @@
 /Syllabore/.vs/Syllabore/v17
 /Syllabore/.vs/Syllabore/FileContentIndex
 /Syllabore/.vs/ProjectEvaluation
+/Syllabore/Syllabore.Example/bin/Debug/net7.0

Syllabore/Syllabore.Example/Syllabore.Example.csproj

@@ -2,7 +2,7 @@
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>net5.0</TargetFramework>
+    <TargetFramework>net7.0</TargetFramework>
   </PropertyGroup>
 
   <ItemGroup>

Syllabore/Syllabore/DefaultSyllableGenerator.cs

@@ -1,17 +1,23 @@
 using System;
 using System.Collections.Generic;
 using System.Text;
+using static System.Net.WebRequestMethods;
 
 namespace Syllabore
 {
     /// <summary>
-    /// <para>
     /// The default syllable provider used by a vanilla instance
     /// of <see cref="NameGenerator"/>.
-    /// </para>
     /// </summary>
     public class DefaultSyllableGenerator : SyllableGenerator
     {
+        /// <summary>
+        /// Instantiates a new <see cref="DefaultSyllableGenerator"/>
+        /// containing a subset of consonants and vowels from the English
+        /// language. See further details in the wiki at
+        /// <a href="https://github.com/kesac/Syllabore/wiki/DefaultSyllableGenerator">
+        /// https://github.com/kesac/Syllabore/wiki/DefaultSyllableGenerator</a>.
+        /// </summary>
         public DefaultSyllableGenerator()
         {
             this.WithLeadingConsonants("bdlmprst");
@@ -22,7 +28,6 @@ public DefaultSyllableGenerator()
             this.WithProbability(x => x
                     .OfLeadingConsonants(0.95, 0.25)
                     .OfFinalConsonants(0.50, 0.25));
-
         }
     }
 }

Syllabore/Syllabore/DeprecatedDefaultNameTransformer.cs

@@ -5,8 +5,10 @@
 namespace Syllabore
 {
     /// <summary>
-    /// This transformer creates variations of names by replacing one syllable
-    /// with another syllable. Syllables are derived from <see cref="DefaultSyllableGenerator"/>.
+    /// <b>Deprecated</b>. This transformer was originally used to 
+    /// create variations of names by replacing one syllable
+    /// with another syllable. Syllables were derived from 
+    /// <see cref="DefaultSyllableGenerator"/>.
     /// </summary>
     [Obsolete("No longer used", false)]
     public class DefaultNameTransformer : NameTransformer
@@ -15,6 +17,9 @@ public class DefaultNameTransformer : NameTransformer
 
         private Random Random { get; set; }
 
+        /// <summary>
+        /// Deprecated. No longer used.
+        /// </summary>
         [Obsolete("No longer used", false)]
         public DefaultNameTransformer()
         {

Syllabore/Syllabore/DeprecatedNameTransformer.cs

@@ -4,6 +4,9 @@
 
 namespace Syllabore
 {
+    /// <summary>
+    /// Deprecated. Use <see cref="TransformSet"/> instead.
+    /// </summary>
     [Obsolete("Use TransformSet instead", false)]
     public class NameTransformer : TransformSet { }
 }

Syllabore/Syllabore/GeneratorProbability.cs

@@ -6,22 +6,68 @@
 namespace Syllabore
 {
     /// <summary>
-    /// Contains probability settings in a <see cref="SyllableGenerator"/>.
+    /// Contains the probability settings of a <see cref="SyllableGenerator"/>.
     /// </summary>
     public class GeneratorProbability
     {
+        /// <summary>
+        /// The probability that a leading vowel exists in the starting syllable. In other
+        /// words, this is the probability that a name starts with a vowel rather than a consonant.
+        /// </summary>
         public double? ChanceStartingSyllableLeadingVowelExists { get; set; }
+
+        /// <summary>
+        /// The probability that a leading vowel in the starting syllable is a sequence. In other
+        /// words, this is the probability that a name starts with a vowel sequence rather than a consonant.
+        /// </summary>
         public double? ChanceStartingSyllableLeadingVowelIsSequence { get; set; }
+
+        /// <summary>
+        /// The probability that a leading consonant exists in a syllable. A leading
+        /// consonant is a consonant that appears before a vowel in a syllable.
+        /// </summary>
         public double? ChanceLeadingConsonantExists { get; set; }
+
+        /// <summary>
+        /// The probability that a leading consonant in a syllable is a sequence. A leading
+        /// consonant sequence is a consonant sequence that appears before a vowel in a syllable.
+        /// </summary>
         public double? ChanceLeadingConsonantIsSequence { get; set; }
+
+        /// <summary>
+        /// The probability that a vowel exists in a syllable.
+        /// </summary>
         public double? ChanceVowelExists { get; set; }
+
+        /// <summary>
+        /// The probability that a vowel in a syllable is a sequence.
+        /// </summary>
         public double? ChanceVowelIsSequence { get; set; }
+
+        /// <summary>
+        /// The probability that a trailing consonant exists in a syllable. A trailing
+        /// consonant is a consonant that appears after a vowel in a syllable.
+        /// </summary>
         public double? ChanceTrailingConsonantExists { get; set; }
+
+        /// <summary>
+        /// The probability that a trailing consonant in a syllable is a sequence. A trailing
+        /// consonant is a consonant that appears after a vowel in a syllable.
+        /// </summary>
         public double? ChanceTrailingConsonantIsSequence { get; set; }
-        public double? ChanceFinalConsonantExists { get; set; }
-        public double? ChanceFinalConsonantIsSequence { get; set; }
 
-        public GeneratorProbability() { }
+        /// <summary>
+        /// The probability that a final consonant exists in a syllable. Final consonants
+        /// are the same as trailing consonants excecpt they only appear in the final
+        /// syllable of a name.
+        /// </summary>
+        public double? ChanceFinalConsonantExists { get; set; }
 
+        /// <summary>
+        /// The probability that a final consonant in a syllable is a sequence. Final consonants
+        /// are the same as trailing consonants excecpt they only appear in the final
+        /// syllable of a name.
+        /// </summary>
+        public double? ChanceFinalConsonantIsSequence { get; set; }
     }
 }

Syllabore/Syllabore/Grapheme.cs

@@ -6,18 +6,27 @@ namespace Syllabore
 {
     /// <summary>
     /// <para>
-    /// A <see cref="Grapheme"/> is the most basic indivisible unit
-    /// of a writing system. In Syllabore, they 
-    /// can represent a single vowel, consonant, or sequence.
-    /// </para>
-    /// <para>
-    /// <see cref="Grapheme"/>s are used by <see cref="SyllableGenerator"/>s
-    /// to construct syllables.
+    /// A <see cref="Grapheme"/> is an indivisible unit of a 
+    /// writing system. In Syllabore, <see cref="Grapheme">Graphemes</see> 
+    /// are used to represent vowels, consonants, or sequences.
+    /// <see cref="Grapheme">Graphemes</see> are used directly by 
+    /// <see cref="SyllableGenerator">SyllableGenerators</see>
+    /// when constructing syllables.
     /// </para>
     /// </summary>
     public class Grapheme : IWeighted
     {
+        /// <summary>
+        /// The vowel, consonant, or sequence that 
+        /// this <see cref="Grapheme"/> represents.
+        /// </summary>
         public string Value { get; set; }
+
+        /// <summary>
+        /// The weight of occurrence for this
+        /// <see cref="Grapheme"/>. By default the
+        /// value is 1.
+        /// </summary>
         public int Weight { get; set; }
 
         /// <summary>

Syllabore/Syllabore/INameGenerator.cs

@@ -11,7 +11,8 @@ namespace Syllabore
     public interface INameGenerator : IGenerator<string>
     {
         /// <summary>
-        /// Returns a new name of the specified syllable length.
+        /// Returns a string representing a name of the specified syllable length.
+        /// Note that syllable length is not the same as string length.
         /// </summary>
         string Next(int syllableLength);
 
@@ -22,6 +23,7 @@ public interface INameGenerator : IGenerator<string>
 
         /// <summary>
         /// Returns a new <see cref="Name"/> of the specified syllable length.
+        /// Note that syllable length is not the same as string length.
         /// </summary>
         Name NextName(int syllableLength);
     }

Syllabore/Syllabore/Json/JsonPropertyCast.cs

@@ -6,20 +6,34 @@
 
 namespace Syllabore.Json
 {
+    /// <summary>
+    /// A special kind of <see cref="JsonConverter{Transform}"/> 
+    /// that's only role is to cast the value of a property to a different <see cref="Type"/>.
+    /// </summary>
     public class JsonPropertyCast<T> : JsonConverter<T>
     {
         private Type TargetType;
 
+        /// <summary>
+        /// Instantiates a new <see cref="JsonPropertyCast{T}"/> that will
+        /// cast properties to the specified <see cref="Type"/>.
+        /// </summary>
         public JsonPropertyCast(Type targetType)
         {
             this.TargetType = targetType;
         }
 
+        /// <summary>
+        /// Override. Reads the value of a property and casts it to the specified <see cref="Type"/>.
+        /// </summary>
         public override T Read(ref Utf8JsonReader reader, Type typeToConvert, JsonSerializerOptions options)
         {
             return (T)JsonSerializer.Deserialize(ref reader, this.TargetType, options);
         }
 
+        /// <summary>
+        /// Override. Writes the value of a property and casts it to the specified <see cref="Type"/>.
+        /// </summary>
         public override void Write(Utf8JsonWriter writer, T value, JsonSerializerOptions options)
         {
             JsonSerializer.Serialize(writer, value, this.TargetType, options);

Syllabore/Syllabore/Json/NameGeneratorSerializer.cs

@@ -22,10 +22,27 @@ public class NameGeneratorSerializer
         /// </summary>
         private static readonly char[] AllowedCharacters = { '\r', '\n', '\u0022' };
 
-        public Type ProviderType { get; set; }
+        /// <summary>
+        /// The class <see cref="Type"/> of a <see cref="NameGenerator"/>'s
+        /// <see cref="NameGenerator.Provider"/> property.
+        /// </summary>
+        public Type ProviderType { get; set; }    // TODO: Rename
+
+        /// <summary>
+        /// The class <see cref="Type"/> of a <see cref="NameGenerator"/>'s
+        /// <see cref="NameGenerator.Transformer"/> property.
+        /// </summary>
         public Type TransformerType { get; set; }
+
+        /// <summary>
+        /// The class <see cref="Type"/> of a <see cref="NameGenerator"/>'s
+        /// <see cref="NameGenerator.Filter"/> property.
+        /// </summary>
         public Type FilterType { get; set; }
 
+        /// <summary>
+        /// Creates a new instance of <see cref="NameGeneratorSerializer"/>.
+        /// </summary>
         public NameGeneratorSerializer()
         {
             this.ProviderType = typeof(SyllableGenerator);

Syllabore/Syllabore/Name.cs

@@ -9,20 +9,20 @@ namespace Syllabore
     public class Name
     {
         /// <summary>
-        /// Ordered syllables that make up this name.
+        /// The ordered syllables that make up this name.
         /// </summary>
         public List<string> Syllables { get; set; }
 
         /// <summary>
-        /// An empty name.
+        /// Instantiates an empty name.
         /// </summary>
         public Name()
         {
             this.Syllables = new List<string>();
         }
 
         /// <summary>
-        /// Instantiates a name with the desired starting syllables.
+        /// Instantiates a new name with the desired starting syllables.
         /// </summary>
         /// <param name="syllable"></param>
         public Name(params string[] syllable)
@@ -31,7 +31,7 @@ public Name(params string[] syllable)
         }
 
         /// <summary>
-        /// Instantiates a name that is a copy of the specified name. (This constructor
+        /// Instantiates a new name that is a copy of the specified name. (This constructor
         /// is useful for a <see cref="INameTransformer"/>.)
         /// </summary>
         /// <param name="copy"></param>
@@ -50,16 +50,26 @@ public override string ToString()
             return result.Substring(0, 1).ToUpper() + result.Substring(1).ToLower();
         }
 
+        /// <summary>
+        /// A <see cref="Name"/> is equal to another
+        /// <see cref="Name"/> if and only if their
+        /// string representations are also equal.
+        /// </summary>
         public override bool Equals(object obj)
         {
-            if(obj is Name){
-                return (((Name)obj).ToString() == this.ToString());
+            if (obj is Name name)
+            {
+                return (name.ToString() == this.ToString());
             }
 
             return false;
         }
 
-        public override int GetHashCode()
+
+        /// <summary>
+        /// Returns a hash code for this <see cref="Name"/>.
+        /// </summary>
+        public override int GetHashCode() // Needs to exist for the Equals() override.
         {
             return base.GetHashCode();
         }