From 89561ee2e80e1a422a358157a36b226f49c856f2 Mon Sep 17 00:00:00 2001 From: Brian Ball Date: Tue, 29 Jan 2019 22:11:04 -0500 Subject: [PATCH] Finished adding XML comments on all publically visible types/members --- Args/Help/ResourceMemberHelpAttributeBase.cs | 7 +- Args/IArgsConfiguration.cs | 18 +++-- Args/IArgsTypeConverter.cs | 12 +-- Args/IInitializeModelBindingDefinition.cs | 5 ++ Args/IMemberBindingDefinition.cs | 37 ++++++++- Args/IModelBindingDefinition.cs | 65 ++++++++++++++++ Args/InvalidArgsFormatException.cs | 22 +++++- Args/LambdaArgsTypeConverter.cs | 12 ++- Args/MemberBindingDefinition.cs | 60 ++++++++++++--- Args/ModelBindingDefinition.cs | 81 +++++++++++++++++++- 10 files changed, 288 insertions(+), 31 deletions(-) diff --git a/Args/Help/ResourceMemberHelpAttributeBase.cs b/Args/Help/ResourceMemberHelpAttributeBase.cs index d70384e..d80a063 100644 --- a/Args/Help/ResourceMemberHelpAttributeBase.cs +++ b/Args/Help/ResourceMemberHelpAttributeBase.cs @@ -1,7 +1,4 @@ using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; namespace Args.Help { @@ -14,6 +11,10 @@ namespace Args.Help [AttributeUsage(AttributeTargets.Property | AttributeTargets.Field | AttributeTargets.Class)] public abstract class ResourceMemberHelpAttributeBase : Attribute { + /// + /// Returns the helptext provided by the implementation of + /// + /// public abstract string GetHelpText(); } } diff --git a/Args/IArgsConfiguration.cs b/Args/IArgsConfiguration.cs index 40db946..c115ab3 100644 --- a/Args/IArgsConfiguration.cs +++ b/Args/IArgsConfiguration.cs @@ -1,16 +1,22 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; - -namespace Args +namespace Args { /// /// An interface that will configure an IModelBindingDefinition based on a given initializer /// public interface IArgsConfiguration { + /// + /// When implemented, this method will configure the model binder + /// + /// + /// IModelBindingDefinition Configure(); + /// + /// When implemented, this method will configure the model binder with the provided initializer + /// + /// + /// + /// IModelBindingDefinition Configure(IModelBindingDefinitionInitializer initalizer); } } diff --git a/Args/IArgsTypeConverter.cs b/Args/IArgsTypeConverter.cs index 3dda306..05a0d3e 100644 --- a/Args/IArgsTypeConverter.cs +++ b/Args/IArgsTypeConverter.cs @@ -1,15 +1,15 @@ -using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; - -namespace Args +namespace Args { /// /// A simple interface to impelment for type conversion from string. If a TypeConverter for the type does not already exist, this is the easiest way to do type conversion in Args /// public interface IArgsTypeConverter { + /// + /// When implemented, this method will convert the provided value + /// + /// + /// object Convert(string value); } } diff --git a/Args/IInitializeModelBindingDefinition.cs b/Args/IInitializeModelBindingDefinition.cs index 80b48f0..70e948f 100644 --- a/Args/IInitializeModelBindingDefinition.cs +++ b/Args/IInitializeModelBindingDefinition.cs @@ -6,6 +6,11 @@ namespace Args /// public interface IModelBindingDefinitionInitializer { + /// + /// When implemented, this method will initialize the provided + /// + /// + /// void Initialize(IModelBindingDefinition init); } } diff --git a/Args/IMemberBindingDefinition.cs b/Args/IMemberBindingDefinition.cs index bab06f7..4485047 100644 --- a/Args/IMemberBindingDefinition.cs +++ b/Args/IMemberBindingDefinition.cs @@ -1,6 +1,6 @@ using System.Collections.Generic; -using System.Reflection; using System.ComponentModel; +using System.Reflection; namespace Args { @@ -10,18 +10,53 @@ namespace Args /// Type of the model to bind public interface IMemberBindingDefinition { + /// + /// Returns the parent that the current member belongs to + /// IModelBindingDefinition Parent { get; } + /// + /// Returns the of the current member binding definition + /// MemberInfo MemberInfo { get; } + /// + /// Gets or sets the type converter that will be used to parse the value for the current member + /// TypeConverter TypeConverter { get; set; } + /// + /// Holds the collection of switch value(s) that will bind to the current member binding definition + /// ICollection SwitchValues { get; } + /// + /// Gets or sets the default value to use if no value is provided + /// object DefaultValue { get; set; } + /// + /// When implemented, returns a value that indicates if the provided witch is handled by the current member + /// + /// + /// bool CanHandleSwitch(string s); + /// + /// Gets or sets the help text value for the current member + /// string HelpText { get; set; } + /// + /// Indicates if the current member is reuired + /// bool Required { get; set; } } + /// + /// Extension methods that applies to all instances of the interface + /// public static class MemberBindingDefinitionExtensions { + /// + /// Returns an object that will allow the member binding to be fluently configured + /// + /// + /// + /// public static FluentMemberBindingConfiguration AsFluent(this IMemberBindingDefinition source) { return new FluentMemberBindingConfiguration(source); diff --git a/Args/IModelBindingDefinition.cs b/Args/IModelBindingDefinition.cs index 0a32a3e..9499770 100644 --- a/Args/IModelBindingDefinition.cs +++ b/Args/IModelBindingDefinition.cs @@ -11,25 +11,90 @@ namespace Args /// Type of the model to bind public interface IModelBindingDefinition { + /// + /// A dictionary of type converters to use for the specified types + /// IDictionary TypeConverters { get; } + /// + /// The string value that indicates the start of a command switch + /// string SwitchDelimiter { get; set; } + /// + /// The to use when comparing swtich values + /// StringComparer StringComparer { get; set; } + /// + /// The collection of configured members for the model + /// IEnumerable> Members { get; } + /// + /// The description for the model; for use when help text is requested + /// string CommandModelDescription { get; set; } + /// + /// Gets or creates an for the provided member + /// + /// + /// IMemberBindingDefinition GetOrCreateMemberBindingDefinition(MemberInfo member); + /// + /// Gets an for the provided member + /// + /// + /// IMemberBindingDefinition GetMemberBindingDefinition(MemberInfo member); + /// + /// Creates an instance of and binds members based on the provided args + /// + /// + /// TModel CreateAndBind(IEnumerable args); + /// + /// Binds the provided to the provided + /// + /// + /// void BindModel(TModel model, IEnumerable args); + /// + /// Adds the provided as an ordinal argument + /// + /// void AddOrdinalArgument(MemberInfo member); + /// + /// Sets the provided as the ordinal arguments + /// + /// void SetOrdinalArguments(IEnumerable members); + /// + /// Gets the configured ordinal arguments + /// + /// IEnumerable GetOrdinalArguments(); + /// + /// Removes a previously configured + /// + /// void RemoveMember(MemberInfo member); + /// + /// Retrives the ordinal index of the provided ; Returns if the provided is not an ordinal member + /// + /// + /// int? OrdinalIndexOf(MemberInfo member); } + /// + /// Helpful extension methods for + /// public static class ModelBindingDefinitionExtensions { + /// + /// Returns an object that allows the model to be configured fluently + /// + /// + /// + /// public static FluentModelBindingConfiguration AsFluent(this IModelBindingDefinition source) { return new FluentModelBindingConfiguration(source); diff --git a/Args/InvalidArgsFormatException.cs b/Args/InvalidArgsFormatException.cs index a77710c..bd92571 100644 --- a/Args/InvalidArgsFormatException.cs +++ b/Args/InvalidArgsFormatException.cs @@ -2,14 +2,34 @@ namespace Args { - [Serializable] + /// + /// An exception thrown if the provided args are not in a format that can be parsed + /// + [Serializable] public class InvalidArgsFormatException : Exception { + /// + /// + /// public InvalidArgsFormatException() { } + /// + /// + /// + /// public InvalidArgsFormatException(string message) : base(message) { } + /// + /// + /// + /// + /// public InvalidArgsFormatException(string message, Exception inner) : base(message, inner) { } #if !NETSTANDARD_1_3 + /// + /// + /// + /// + /// protected InvalidArgsFormatException( System.Runtime.Serialization.SerializationInfo info, System.Runtime.Serialization.StreamingContext context) diff --git a/Args/LambdaArgsTypeConverter.cs b/Args/LambdaArgsTypeConverter.cs index 95848b0..b91e2a0 100644 --- a/Args/LambdaArgsTypeConverter.cs +++ b/Args/LambdaArgsTypeConverter.cs @@ -1,7 +1,4 @@ using System; -using System.Collections.Generic; -using System.Linq; -using System.Text; namespace Args { @@ -12,11 +9,20 @@ public class LambdaArgsTypeConverter : IArgsTypeConverter { private readonly Func converter; + /// + /// + /// + /// public LambdaArgsTypeConverter(Func converter) { this.converter = converter; } + /// + /// Converts the provided + /// + /// + /// public object Convert(string value) { return converter(value); diff --git a/Args/MemberBindingDefinition.cs b/Args/MemberBindingDefinition.cs index b7b5f69..852e749 100644 --- a/Args/MemberBindingDefinition.cs +++ b/Args/MemberBindingDefinition.cs @@ -1,11 +1,11 @@ using System; +using System.Collections; using System.Collections.Generic; using System.Collections.ObjectModel; using System.ComponentModel; +using System.Globalization; using System.Linq; using System.Reflection; -using System.Collections; -using System.Globalization; namespace Args { @@ -15,6 +15,9 @@ namespace Args /// Type of model to bind public class MemberBindingDefinition : IMemberBindingDefinition { + /// + /// Returns the for the current member + /// public virtual ModelBindingDefinition Parent { get; protected set; } IModelBindingDefinition IMemberBindingDefinition.Parent @@ -22,23 +25,43 @@ IModelBindingDefinition IMemberBindingDefinition.Parent get { return Parent; } } - + /// + /// Gets the of the current member + /// public MemberInfo MemberInfo { get; protected set; } + /// + /// Gets or sets the used to parse a value for the current member + /// public virtual TypeConverter TypeConverter { get; set; } + /// + /// Gets the allowed switch values + /// public virtual ICollection SwitchValues { get; private set; } + /// + /// Gets or sets the default value to use if no value is provided + /// public virtual object DefaultValue { get; set; } + /// + /// Gets or sets of the member is requird when binding + /// public virtual bool Required { get; set; } - public virtual bool CanHandleSwitch(string s) - { - return SwitchValues.Contains(s, Parent.StringComparer); - } - - + /// + /// Indicates of the provided string is one of the allowed switch values + /// + /// + /// + public virtual bool CanHandleSwitch(string s) => SwitchValues.Contains(s, Parent.StringComparer); + + /// + /// + /// + /// + /// public MemberBindingDefinition(MemberInfo memberInfo, ModelBindingDefinition parent) { if (memberInfo.DeclaringType.IsAssignableFrom(typeof(TModel)) == false) throw new InvalidOperationException(String.Format("memberInfo must be from type {0}", typeof(TModel).FullName)); @@ -47,6 +70,12 @@ public MemberBindingDefinition(MemberInfo memberInfo, ModelBindingDefinition(); } + /// + /// Attempts to prase the provided value(s) for the current member + /// + /// + /// + /// public virtual object CoerceValue(IEnumerable value, TModel model) { var declaredType = MemberInfo.GetDeclaredType(); @@ -102,17 +131,30 @@ public virtual object CoerceValue(IEnumerable value, TModel model) return newValue; } + /// + /// Sets the value fo the current member + /// + /// + /// public virtual void SetMemberValue(object value, TModel model) { MemberInfo.SetValue(model, value); } + /// + /// Gets the default type converter for the type of the current member + /// + /// + /// public virtual TypeConverter GetDefaultTypeConveter(Type type) { return TypeDescriptor.GetConverter(type); } private string helpText; + /// + /// Gets or sets the help text fo rthe current member + /// public virtual string HelpText { get diff --git a/Args/ModelBindingDefinition.cs b/Args/ModelBindingDefinition.cs index 75d07dd..748893f 100644 --- a/Args/ModelBindingDefinition.cs +++ b/Args/ModelBindingDefinition.cs @@ -7,6 +7,10 @@ namespace Args { + /// + /// The default implementation + /// + /// public class ModelBindingDefinition : IModelBindingDefinition { /// @@ -22,16 +26,34 @@ IEnumerable> IModelBindingDefinition.Me } } + /// + /// + /// public virtual IDictionary TypeConverters { get; private set; } + /// + /// + /// protected virtual IList OrdinalArguments { get; set; } + /// + /// + /// public virtual string SwitchDelimiter { get; set; } + /// + /// + /// public virtual StringComparer StringComparer { get; set; } + /// + /// + /// public string CommandModelDescription { get; set; } + /// + /// + /// public ModelBindingDefinition() { Members = new Dictionary>(); @@ -41,6 +63,11 @@ public ModelBindingDefinition() StringComparer = System.StringComparer.CurrentCultureIgnoreCase; } + /// + /// + /// + /// + /// public virtual TypeConverter TryGetTypeConverter(Type type) { TypeConverter returnValue; @@ -50,6 +77,11 @@ public virtual TypeConverter TryGetTypeConverter(Type type) return null; } + /// + /// + /// + /// + /// public virtual IMemberBindingDefinition GetOrCreateMemberBindingDefinition(MemberInfo member) { @@ -64,6 +96,11 @@ public virtual IMemberBindingDefinition GetOrCreateMemberBindingDefiniti return returnValue; } + /// + /// + /// + /// + /// public virtual IMemberBindingDefinition GetMemberBindingDefinition(MemberInfo member) { var memberPair = Members.Where(m => m.Key.Name == member.Name); @@ -72,6 +109,11 @@ public virtual IMemberBindingDefinition GetMemberBindingDefinition(Membe } #region Binding Methods + /// + /// + /// + /// + /// public virtual TModel CreateAndBind(IEnumerable args) { var model = (TModel) ArgsTypeResolver.Current.GetService(typeof(TModel)); @@ -95,6 +137,11 @@ private void EnsureCorrectNumberOfOrdinalArguments(IEnumerable ordinalAr } } + /// + /// + /// + /// + /// public virtual void BindModel(TModel model, IEnumerable args) { var unnamedArgs = args.TakeWhile(s => IsSwitch(s) == false); @@ -142,6 +189,12 @@ public virtual void BindModel(TModel model, IEnumerable args) } } + /// + /// + /// + /// + /// + /// protected virtual void HandleInputs(IEnumerable arguments, TModel model, MemberBindingDefinition memberBindingDefinition) { var result = memberBindingDefinition.CoerceValue(arguments, model); @@ -149,13 +202,21 @@ protected virtual void HandleInputs(IEnumerable arguments, TModel model, memberBindingDefinition.SetMemberValue(result, model); } + /// + /// + /// + /// + /// protected virtual bool IsSwitch(string value) { return value.StartsWith(SwitchDelimiter); } #endregion - + /// + /// + /// + /// public void AddOrdinalArgument(MemberInfo member) { if (OrdinalArguments.Any(m => m.GetDeclaredType().GetGenericIEnumerable() != null)) @@ -165,18 +226,29 @@ public void AddOrdinalArgument(MemberInfo member) OrdinalArguments.Add(member); } + /// + /// + /// + /// public void SetOrdinalArguments(IEnumerable members) { foreach (var member in members) AddOrdinalArgument(member); } + /// + /// + /// + /// public IEnumerable GetOrdinalArguments() { return new ReadOnlyCollection(OrdinalArguments); } - + /// + /// + /// + /// public void RemoveMember(MemberInfo member) { if (Members.ContainsKey(member)) @@ -186,6 +258,11 @@ public void RemoveMember(MemberInfo member) } } + /// + /// + /// + /// + /// public int? OrdinalIndexOf(MemberInfo member) { var index = OrdinalArguments.IndexOf(member);