Improved XML documentation comments on Faker[T] API.

HISTORY.md

@@ -1,3 +1,6 @@
+## v22.1.2
+* Improved XML documentation comments on `Faker[T]` API.
+
 ## v22.1.1
 * PR 144: Argument support for mustache handlebars. Example: `{{name.firstname(Male)}}`
 * Using **C# 7.3** generic `Enum` constraints for methods that only accept enums. Example: `f.PickRandom<Enum>()`.

Source/Bogus/Faker[T].cs

@@ -36,7 +36,7 @@ public interface IFakerTInternal
    }
 
    /// <summary>
-   /// Generates fake objects of T.
+   /// Generates fake objects of <typeparamref name="T"/>.
    /// </summary>
    /// <typeparam name="T">The object to fake.</typeparam>
    public class Faker<T> : IFakerTInternal, ILocaleAware, IRuleSet<T> where T : class
@@ -68,9 +68,9 @@ public class Faker<T> : IFakerTInternal, ILocaleAware, IRuleSet<T> where T : cla
       Type IFakerTInternal.TypeOfT => typeof(T);
 
       /// <summary>
-      /// Clones the internal state of a Faker[T] into a new Faker[T] so that
+      /// Clones the internal state of a <seealso cref="Faker{T}"/> into a new <seealso cref="Faker{T}"/> so that
       /// both are isolated from each other. The clone will have internal state
-      /// reset as if .Generate() was never
+      /// reset as if <seealso cref="Generate(string)"/> was never called.
       /// </summary>
       public Faker<T> Clone()
       {
@@ -145,10 +145,10 @@ public Faker(string locale = "en", IBinder binder = null)
       }
 
       /// <summary>
-      /// Creates a seed locally scoped within this Faker[T] ignoring the globally scoped Randomzier.Seed.
-      /// If this method is never called the global Randomizer.Seed is used.
+      /// Creates a seed locally scoped within this <seealso cref="Faker{T}"/> ignoring the globally scoped <seealso cref="Randomizer.Seed"/>.
+      /// If this method is never called the global <seealso cref="Randomizer.Seed"/> is used.
       /// </summary>
-      /// <para name="seed">The seed value to use within this Faker[T] instance.</para>
+      /// <param name="seed">The seed value to use within this <seealso cref="Faker{T}"/> instance.</param>
       public virtual Faker<T> UseSeed(int seed)
       {
          this.localSeed = seed;
@@ -157,7 +157,8 @@ public virtual Faker<T> UseSeed(int seed)
       }
 
       /// <summary>
-      /// Uses the factory method to generate new instances.
+      /// Instructs <seealso cref="Faker{T}"/> to use the factory method as a source
+      /// for new instances of <typeparamref name="T"/>.
       /// </summary>
       public virtual Faker<T> CustomInstantiator(Func<Faker, T> factoryMethod)
       {
@@ -221,9 +222,10 @@ protected virtual Faker<T> RuleFor<TProperty>(string propertyOrField, Func<Faker
       }
 
       /// <summary>
-      /// Gives you a way to specify multiple rules inside an action
-      /// without having to call RuleFor multiple times. Note: StrictMode
-      /// must be false since property rules cannot be individually checked.
+      /// Specify multiple rules inside an action without having to call
+      /// RuleFor multiple times. Note: <seealso cref="StrictMode"/> must be false
+      /// since rules for properties and fields cannot be individually checked when
+      /// using this method.
       /// </summary>
       public virtual Faker<T> Rules(Action<Faker, T> setActions)
       {
@@ -262,7 +264,10 @@ public void RuleFor<TProperty>(Expression<Func<T, TProperty>> property)
       }
 
       /// <summary>
-      /// Creates a rule for a type on a class
+      /// Creates one rule for all types of <typeparamref name="TType"/> on type <typeparamref name="T"/>.
+      /// In other words, if you have <typeparamref name="T"/> with many fields or properties of
+      /// type <seealso cref="Int32"/> this method allows you to specify a rule for all fields or
+      /// properties of type <seealso cref="Int32"/>.
       /// </summary>
       public virtual Faker<T> RuleForType<TType>(Type type, Func<Faker, TType> setterForType)
       {
@@ -302,9 +307,11 @@ protected virtual Type GetFieldOrPropertyType(MemberInfo mi)
       }
 
       /// <summary>
-      /// Create a rule set that can be executed in specialized cases.
+      /// Defines a set of rules under a specific name. Useful for defining
+      /// rules for special cases. Note: The name `default` is the name of all rules that are
+      /// defined without an explicit rule set.
       /// </summary>
-      /// <param name="ruleSetName">The rule set name</param>
+      /// <param name="ruleSetName">The rule set name.</param>
       /// <param name="action">The set of rules to apply when this rules set is specified.</param>
       public virtual Faker<T> RuleSet(string ruleSetName, Action<IRuleSet<T>> action)
       {
@@ -316,11 +323,10 @@ public virtual Faker<T> RuleSet(string ruleSetName, Action<IRuleSet<T>> action)
       }
 
       /// <summary>
-      /// Ignore a property or field when using StrictMode.
+      /// Ignores a property or field when <seealso cref="StrictMode"/> is enabled.
       /// </summary>
       /// <typeparam name="TPropertyOrField"></typeparam>
       /// <param name="propertyOrField"></param>
-      /// <returns></returns>
       public virtual Faker<T> Ignore<TPropertyOrField>(Expression<Func<T, TPropertyOrField>> propertyOrField)
       {
          var propNameOrField = PropertyName.For(propertyOrField);
@@ -342,20 +348,22 @@ public virtual Faker<T> Ignore<TPropertyOrField>(Expression<Func<T, TPropertyOrF
 
          return this;
       }
-
+      
       /// <summary>
-      /// Ensures all properties of T have rules.
+      /// When set to true, ensures all properties and public fields of <typeparamref name="T"/> have rules
+      /// before an object of <typeparamref name="T"/> is populated or generated. Manual assertion
+      /// can be invoked using <seealso cref="Validate"/> and <seealso cref="AssertConfigurationIsValid"/>.
       /// </summary>
-      /// <param name="ensureRulesForAllProperties">Overrides any global setting in Faker.DefaultStrictMode</param>
-      /// <returns></returns>
+      /// <param name="ensureRulesForAllProperties">Overrides any global setting in <seealso cref="Faker.DefaultStrictMode"/>.</param>
       public virtual Faker<T> StrictMode(bool ensureRulesForAllProperties)
       {
          this.StrictModes[currentRuleSet] = ensureRulesForAllProperties;
          return this;
       }
 
       /// <summary>
-      /// Action is invoked after all the rules are applied.
+      /// A finalizing action rule applied to <typeparamref name="T"/> after all the rules
+      /// are executed.
       /// </summary>
       public virtual Faker<T> FinishWith(Action<Faker, T> action)
       {
@@ -381,8 +389,16 @@ protected virtual string[] ParseDirtyRulesSets(string dirtyRules)
       }
 
       /// <summary>
-      /// Generates a fake object of T.
+      /// Generates a fake object of <typeparamref name="T"/> using the specified rules in this
+      /// <seealso cref="Faker{T}"/>.
       /// </summary>
+      /// <param name="ruleSets">A comma separated list of rule sets to execute.
+      /// Note: The name `default` is the name of all rules defined without an explicit rule set.
+      /// When a custom rule set name is provided in <paramref name="ruleSets"/> as parameter,
+      /// the `default` rules will not run. If you want rules without an explicit rule set to run
+      /// you'll need to include the `default` rule set name in the comma separated
+      /// list of rules to run. (ex: "rulesetA, rulesetB, default")
+      /// </param>
       public virtual T Generate(string ruleSets = null)
       {
          Func<Faker, T> createRule = null;
@@ -411,8 +427,17 @@ public virtual T Generate(string ruleSets = null)
       }
 
       /// <summary>
-      /// Generates multiple fake objects of T.
+      /// Generates a <seealso cref="List{T}"/> fake objects of type <typeparamref name="T"/> using the specified rules in
+      /// this <seealso cref="Faker{T}"/>.
       /// </summary>
+      /// <param name="count">The number of items to create in the <seealso cref="List{T}"/>.</param>
+      /// <param name="ruleSets">A comma separated list of rule sets to execute.
+      /// Note: The name `default` is the name of all rules defined without an explicit rule set.
+      /// When a custom rule set name is provided in <paramref name="ruleSets"/> as parameter,
+      /// the `default` rules will not run. If you want rules without an explicit rule set to run
+      /// you'll need to include the `default` rule set name in the comma separated
+      /// list of rules to run. (ex: "rulesetA, rulesetB, default")
+      /// </param>
       public virtual List<T> Generate(int count, string ruleSets = null)
       {
          return Enumerable.Range(1, count)
@@ -421,9 +446,17 @@ public virtual List<T> Generate(int count, string ruleSets = null)
       }
 
       /// <summary>
-      /// Returns an IEnumerable[T] with LINQ deferred execution. Generated values
-      /// are not guaranteed to be repeatable until .ToList() is called.
+      /// Returns an <seealso cref="IEnumerable{T}"/> with LINQ deferred execution. Generated values
+      /// are not guaranteed to be repeatable until <seealso cref="Enumerable.ToList{T}"/> is called.
       /// </summary>
+      /// <param name="count">The number of items to create in the <seealso cref="IEnumerable{T}"/>.</param>
+      /// <param name="ruleSets">A comma separated list of rule sets to execute.
+      /// Note: The name `default` is the name of all rules defined without an explicit rule set.
+      /// When a custom rule set name is provided in <paramref name="ruleSets"/> as parameter,
+      /// the `default` rules will not run. If you want rules without an explicit rule set to run
+      /// you'll need to include the `default` rule set name in the comma separated
+      /// list of rules to run. (ex: "rulesetA, rulesetB, default")
+      /// </param>
       public virtual IEnumerable<T> GenerateLazy(int count, string ruleSets = null)
       {
          return Enumerable.Range(1, count)
@@ -436,6 +469,13 @@ public virtual IEnumerable<T> GenerateLazy(int count, string ruleSets = null)
       /// amounts of data in a memory efficient way. Generated values *should* be repeatable
       /// for a given seed when starting with the first item in the sequence.
       /// </summary>
+      /// <param name="ruleSets">A comma separated list of rule sets to execute.
+      /// Note: The name `default` is the name of all rules defined without an explicit rule set.
+      /// When a custom rule set name is provided in <paramref name="ruleSets"/> as parameter,
+      /// the `default` rules will not run. If you want rules without an explicit rule set to run
+      /// you'll need to include the `default` rule set name in the comma separated
+      /// list of rules to run. (ex: "rulesetA, rulesetB, default")
+      /// </param>
       public virtual IEnumerable<T> GenerateForever(string ruleSets = null)
       {
          while( true )
@@ -445,17 +485,35 @@ public virtual IEnumerable<T> GenerateForever(string ruleSets = null)
       }
 
       /// <summary>
-      /// Only populates an instance of T.
+      /// Populates an instance of <typeparamref name="T"/> according to the rules
+      /// defined in this <seealso cref="Faker{T}"/>.
       /// </summary>
+      /// <param name="instance">The instance of <typeparamref name="T"/> to populate.</param>
+      /// <param name="ruleSets">A comma separated list of rule sets to execute.
+      /// Note: The name `default` is the name of all rules defined without an explicit rule set.
+      /// When a custom rule set name is provided in <paramref name="ruleSets"/> as parameter,
+      /// the `default` rules will not run. If you want rules without an explicit rule set to run
+      /// you'll need to include the `default` rule set name in the comma separated
+      /// list of rules to run. (ex: "rulesetA, rulesetB, default")
+      /// </param>
       public virtual void Populate(T instance, string ruleSets = null)
       {
          var cleanRules = ParseDirtyRulesSets(ruleSets);
          PopulateInternal(instance, cleanRules);
       }
 
       /// <summary>
-      /// Given an instance of T, populate it with the desired rule sets.
+      /// Populates an instance of <typeparamref name="T"/> according to the rules
+      /// defined in this <seealso cref="Faker{T}"/>.
       /// </summary>
+      /// <param name="instance">The instance of <typeparamref name="T"/> to populate.</param>
+      /// <param name="ruleSets">A comma separated list of rule sets to execute.
+      /// Note: The name `default` is the name of all rules defined without an explicit rule set.
+      /// When a custom rule set name is provided in <paramref name="ruleSets"/> as parameter,
+      /// the `default` rules will not run. If you want rules without an explicit rule set to run
+      /// you'll need to include the `default` rule set name in the comma separated
+      /// list of rules to run. (ex: "rulesetA, rulesetB, default")
+      /// </param>
       protected virtual void PopulateInternal(T instance, string[] ruleSets)
       {
          ValidationResult vr = null;
@@ -519,9 +577,12 @@ protected virtual void PopulateInternal(T instance, string[] ruleSets)
       }
 
       /// <summary>
-      /// Checks if all properties have rules.
+      /// When <seealso cref="StrictMode"/> is enabled, checks if all properties or fields of <typeparamref name="T"/> have
+      /// rules defined. Returns true if all rules are defined, false otherwise.
+      /// The difference between <seealso cref="Validate"/> and <seealso cref="AssertConfigurationIsValid"/>
+      /// is that <seealso cref="Validate"/> will *not* throw <seealso cref="ValidationException"/>
+      /// if some rules are missing when <seealso cref="StrictMode"/> is enabled.
       /// </summary>
-      /// <param name="ruleSets"></param>
       /// <returns>True if validation passes, false otherwise.</returns>
       public virtual bool Validate(string ruleSets = null)
       {
@@ -533,8 +594,13 @@ public virtual bool Validate(string ruleSets = null)
       }
 
       /// <summary>
-      /// Asserts that all properties have rules. When StrictMode is enabled, an exception will be raised
-      /// with complete list of missing rules. Useful in unit tests for fast forward fixing of missing rules.
+      /// Asserts that all properties have rules. When <seealso cref="StrictMode"/> is enabled, an exception will be raised
+      /// with complete list of missing rules. Useful in unit tests to catch missing rules at development
+      /// time. The difference between <seealso cref="Validate"/> and <seealso cref="AssertConfigurationIsValid"/>
+      /// is that <seealso cref="AssertConfigurationIsValid"/> will throw <seealso cref="ValidationException"/>
+      /// if some rules are missing when <seealso cref="StrictMode"/> is enabled. <seealso cref="Validate"/>
+      /// will not throw an exception and will return <seealso cref="bool"/> true or false accordingly if
+      /// rules are missing when <seealso cref="StrictMode"/> is enabled.
       /// </summary>
       /// <exception cref="ValidationException"/>
       public virtual void AssertConfigurationIsValid(string ruleSets = null)
@@ -639,7 +705,7 @@ private ValidationResult ValidateInternal(string[] ruleSets)
       }
 
       /// <summary>
-      /// Provides implicit type conversion from Faker[T] to T. IE: Order testOrder = faker;
+      /// Provides implicit type conversion from <seealso cref="Faker{T}"/> to <typeparamref name="T"/>. IE: Order testOrder = faker;
       /// </summary>
       public static implicit operator T(Faker<T> faker)
       {