Feature/update documentation

docs/ADR/README.md

@@ -0,0 +1,29 @@
+# Architecture Decision Records (ADR)
+
+Architecture Decision Records (ADRs) are documents that capture important architectural decisions made during the development of a MiniMock.
+
+All the ADRs have been approved and are considered final decisions for the project.
+
+## General ADRs [TL;DR](general/TLDR.md)
+
+- [Do We __Really__ Need a New Mocking Framework?](general/DoWeNeedANewMockingFramework.md) - Deciding whether to build a new mocking framework.
+- [Matching Target API in Mock API](general/MatchingTargetApi.md) - Ensures the mock API closely mirrors the target API.
+- [How Strict Should MiniMock Be?](general/HowStrictShouldMiniMockBe.md) - Deciding how strict the framework should be.
+- [No Built-in Assertion Feature](general/NoBuiltInAssertionFeature.md) - Users choose their preferred assertion framework.
+- [No Dependencies to Shared Libraries](general/NoDependencies.md) - Avoid dependencies on shared libraries.
+- [Documentation and Examples](general/DocumentationAndExamples.md) - Approach to documentation and examples for the framework.
+- [Logging and Debugging](general/LoggingAndDebugging.md) - Approach to logging and debugging within the framework.
+
+## Feature Specific ADRs [TL;DR](feature/TLDR.md)
+
+- [Support for Classes and Interfaces](feature/SupportForClassesAndInterfaces.md) - How should classes and interfaces be supported.
+- [Support for Constructors](feature/SupportForConstructors.md) - Decision on supporting constructors in the mocking framework.
+- [Creating Mocks](feature/CreatingMocks.md) - Decision on how to create mocks in the framework.
+- [Support for Methods](feature/SupportForMethods.md) - Decision on supporting methods in the mocking framework.
+- [Support for Properties](feature/SupportForProperties.md) - Decision on supporting properties in the mocking framework.
+- [Support for Events](feature/SupportForEvents.md) - Decision on supporting events in the mocking framework.
+- [Support for Indexers](feature/SupportForIndexers.md) - Decision on supporting indexers in the mocking framework.
+
+## Unsupported Features
+
+- [Unsupported Features](Unsupported/UnsupportedFeatures.md) - Decision on which features not to support.

docs/ADR/Unsupported/UnsupportedFeatures.md

@@ -0,0 +1,23 @@
+# Unsupported features
+
+## Context
+
+In order to keep true to how mocking works some features will not be supported.
+
+## Decision
+
+**Extension methods** are not supported due to their nature. Extension methods are static methods that are called as if they were instance methods of the extended type.
+
+**Sealed classes** are not supported since they can not be inherited from and such do not fit how the framework works.
+
+**Static members** and **Static classes** are not supported due to the way the framework works.
+
+## Consequences
+
+### Positive:
+
+- **No need for magic**: Mocking these features would require breaking the standard supported functionality. 
+
+### Negative:
+
+- **No magic**: Some functionality can be harder to test but if you need to test this maby you have some other issues.

docs/ADR/feature/CreatingMocks.md

@@ -0,0 +1,27 @@
+# Decision on How to Create Mocks
+
+## Context
+
+In the MiniMock framework, there is a need to establish a standardized approach for creating mocks. A consistent and efficient method for creating mocks will enhance the usability and maintainability of the framework.
+
+## Decision
+
+Mocks will be created using a mock factory. The mock factory will provide a centralized and consistent way to create and configure mocks, ensuring that all mocks are created following the same process and standards.
+The constructors of the mock object will remain accessible but should only be used for limited purposes.  
+
+## Consequences
+
+### Positive:
+
+- **Consistency**: Ensures that all mocks are created in a consistent manner.
+- **Centralization**: Provides a single point of control for mock creation, making it easier to manage and update.
+- **Ease of Use**: Simplifies the process of creating mocks for developers.
+
+### Negative:
+
+- **Complexity**: Introduces an additional layer of abstraction, which may add some complexity to the framework.
+- **Maintenance**: Requires ongoing maintenance to ensure the mock factory remains up-to-date with any changes to the framework.
+
+---
+
+More ADRs can be found in the [docs/ADR](../README.md) directory.

docs/ADR/feature/SupportForClassesAndInterfaces.md

@@ -0,0 +1,28 @@
+# Decision on Supporting Classes and Interfaces
+
+## Context
+
+In the MiniMock framework, there is a need to determine the scope of support for mocking different types of members. 
+While interfaces are the primary focus due to their flexibility and common usage in dependency injection, there is also a need to support classes to cover a broader range of use cases.
+
+## Decision
+
+The MiniMock framework will primarily focus on supporting interfaces but will also include support for classes. 
+This approach ensures that the framework can be used in a wide variety of scenarios, providing flexibility and comprehensive mocking capabilities.
+
+## Consequences
+
+### Positive:
+
+- **Flexibility**: Supports a wide range of use cases by allowing both interfaces and classes to be mocked.
+- **Comprehensive**: Provides a robust mocking solution that can handle various types of dependencies.
+- **Usability**: Makes the framework more versatile and useful for developers.
+
+### Negative:
+
+- **Complexity**: Adding support for classes may introduce additional complexity in the framework.
+- **Maintenance**: Requires ongoing maintenance to ensure both interfaces and classes are supported effectively.
+
+---
+
+More ADRs can be found in the [docs/ADR](../README.md) directory.

docs/ADR/feature/SupportForConstructors.md

@@ -0,0 +1,35 @@
+# Decision on Supporting Constructors
+
+## Context
+
+In the MiniMock framework, there is a need to determine the scope of support for mocking constructors.
+
+## Decision
+
+All constructors with the supported access level should be accessible. If no constructor exists, a parameterless constructor is created.
+A factory for each option should be created.
+
+If only internal or private constructors exist, the class is not generated and a warning is registered.
+
+Additionally, the framework should support the following:
+
+- **Parameterized Constructors**: Allow mocking of constructors with parameters, providing flexibility for more complex scenarios.
+- **Constructor Overloads**: Support multiple constructors with different parameter lists.
+- **Dependency Injection**: Enable mocking of constructors that use dependency injection, ensuring compatibility with modern design patterns.
+
+## Consequences
+
+### Positive:
+
+- **Simplicity**: Simplifies the initial implementation by focusing on parameterless constructors.
+- **Flexibility**: Supporting parameterized constructors and overloads provides more flexibility for developers.
+- **Compatibility**: Ensures compatibility with dependency injection, making the framework more versatile.
+
+### Negative:
+
+- **Complexity**: Adding support for parameterized constructors and overloads increases the complexity of the framework.
+- **Maintenance**: Requires ongoing maintenance to ensure that constructor mocking remains robust and up-to-date.
+
+---
+
+More ADRs can be found in the [docs/ADR](../README.md) directory.

docs/ADR/feature/SupportForDelegates.md

@@ -0,0 +1,3 @@
+# Support for Delegates (WIP)
+
+Work in progress.

docs/ADR/feature/SupportForEvents.md

@@ -0,0 +1,31 @@
+# Decision on Supporting Events
+
+## Context
+
+In the MiniMock framework, there is a need to determine the scope of support for mocking events. Events are a crucial part of the C# language, enabling the publisher-subscriber pattern. Supporting all types of events is essential to ensure the framework's flexibility and usability.
+
+## Decision
+
+The MiniMock framework will support mocking all types of events. This includes standard events, custom events, and events with different delegate types. This decision ensures that the framework can handle a wide range of scenarios involving event handling.
+
+Events must be mockable using the following parameters:
+
+- Raise : A method to raise the event, triggering all subscribed handlers.
+- Trigger : A delegate as a out parameter to be used to trigger the event.
+- Add/Remove : Delegates matching the event's add and remove signatures with functionality to be executed.
+
+## Consequences
+
+### Positive:
+
+- **Comprehensive**: Ensures that the framework can handle all types of events, providing flexibility and comprehensive mocking capabilities.
+- **Usability**: Enhances the framework's usability by allowing developers to mock events in various scenarios.
+
+### Negative:
+
+- **Complexity**: Supporting all types of events adds complexity to the framework.
+- **Maintenance**: Requires ongoing maintenance to ensure that event mocking remains robust and up-to-date.
+
+---
+
+More ADRs can be found in the [docs/ADR](../README.md) directory.

docs/ADR/feature/SupportForIndexers.md

@@ -0,0 +1,32 @@
+# Decision on Supporting Indexers
+
+## Context
+
+In the MiniMock framework, there is a need to determine the scope of support for mocking indexers. Indexers allow objects to be indexed in a similar way to arrays, and supporting them is essential for a comprehensive mocking framework.
+
+## Decision
+
+The MiniMock framework will support mocking indexers. This includes both read-only and read-write indexers, ensuring that the framework can handle a wide range of scenarios.
+
+Indexers must be mockable using the following parameters:
+
+- Get/Set : Delegates matching the indexer's getter and setter signature with functionality to be executed.
+- Values : A dictionary optionally containing values to be used as the indexers source.
+
+if none of the above parameters are provided, accessing the indexer must throw a InvalidOperationException with a message in the form "The indexer for '__[indexer type]__' in '__[mocked class]__' is not explicitly mocked.".
+
+## Consequences
+
+### Positive:
+
+- **Comprehensive**: Ensures that the framework can handle indexers in both classes and interfaces.
+- **Flexibility**: Provides developers with the ability to mock different kinds of indexers, enhancing the framework's usability.
+
+### Negative:
+
+- **Complexity**: Supporting both read-only and read-write indexers adds complexity to the framework.
+- **Maintenance**: Requires ongoing maintenance to ensure that indexer mocking remains robust and up-to-date.
+
+---
+
+More ADRs can be found in the [docs/ADR](../README.md) directory.

docs/ADR/feature/SupportForMethods.md

@@ -0,0 +1,57 @@
+# Decision on Supporting Methods
+
+## Context
+
+In the MiniMock framework, there is a need to determine the scope of support for mocking methods. Supporting all standard ways of creating methods is essential to ensure the framework's 
+flexibility and usability. 
+
+The following type of methods must be supported
+- __Asynchronous__ with Task<>, Task, CancellationToken  
+- __Overloaded__ methods in a way that keeps the required effort to setup the mock to a minimum.
+- __Generic__ Including the 'where' __constraints__.
+- __Out__ and __ref__ attributes on the method parameters.
+
+## Decision
+
+The MiniMock framework will support all standard ways of creating methods. This includes instance methods, static methods, virtual methods, and abstract methods. However, support for methods returning `ref` values will require additional work and will be addressed in future updates. See [issue #5](https://github.com/oswaldsql/MiniMock/issues/5)
+
+Methods must be mockable using the following parameters
+
+- Call : A Delegate matching the method signature with functionality to be executed.
+- Throw : An exception to be thrown when the method is called.
+- Return : A value to be returned when the method is called.
+- ReturnValues : A sequence of values to be returned when the method is called multiple times.
+- () : Methods returning `void` can be mocked using an empty delegate.
+
+if none of the above parameters are provided, calling the method must throw a InvalidOperationException with a message in the form "The method '__[method name]__' in '__[mocked class]__' is not explicitly mocked.".
+
+__Asynchronous__ methods are supported. Helper methods are provided to simplify the testing of asynchronous methods. Overloads of the following helper methods are added
+
+- Return : Allows for returning either a Task object or the object to be wrapped in the task object.
+- ReturnValues : Allows for returning either a sequence of Task objects or a sequence of objects to be wrapped in task objects.
+- () : Methods returning Task can also use the empty delegate.
+
+__Overloaded__ methods can either be mocked explicitly by using `Call` or collectively using the following 
+
+- Throw : An exception to be thrown when calling any of the overwritten methods.
+- Return : A value to be returned when a method with that return type is called.
+- ReturnValues : A sequence of values to be returned when a method with those return types is called multiple times.
+- () : Methods returning `void` or `Task` can be mocked using an empty delegate.
+
+Generic methods are supported. The generic type is passed as a type parameter to the 'call' labmda method.
+
+## Consequences
+
+### Positive:
+
+- **Comprehensive**: Ensures that the framework can handle a wide variety of method types.
+- **Flexibility**: Provides developers with the ability to mock different kinds of methods, enhancing the framework's usability.
+
+### Negative:
+
+- **Complexity**: Supporting all standard methods adds complexity to the framework.
+- **Ref Values**: Current issues with methods returning `ref` values need to be resolved, which may require significant effort.
+
+---
+
+More ADRs can be found in the [docs/ADR](../README.md) directory.

docs/ADR/feature/SupportForProperties.md

@@ -0,0 +1,37 @@
+# Decision on Supporting Properties
+
+## Context
+
+In the MiniMock framework, there is a need to determine the scope of support for mocking properties. Properties are a fundamental part of C# classes and interfaces, and supporting them is essential for a comprehensive mocking framework.
+
+## Decision
+
+The MiniMock framework will support mocking both read-only and read-write properties. This includes properties in classes and interfaces, ensuring that the framework can handle a wide range of scenarios.
+
+Properties must be mockable using the following parameters:
+
+- Get/set : Delegates matching the property's getter and setter signature with functionality to be executed.
+- Value : A value to be returned when the property is accessed.
+
+Get-only and set-only properties must only allow mocking of the corresponding getter or setter.
+
+if none of the above parameters are provided, Getting of setting the property must throw a InvalidOperationException with a message in the form "The property '__[property name]__' in '__[mocked class]__' is not explicitly mocked.".
+
+
+## Consequences
+
+### Positive:
+
+- **Comprehensive**: Ensures that the framework can handle properties in both classes and interfaces.
+- **Flexibility**: Provides developers with the ability to mock different kinds of properties, enhancing the framework's usability.
+
+### Negative:
+
+- **Complexity**: Supporting both read-only and read-write properties adds complexity to the framework.
+- **Maintenance**: Requires ongoing maintenance to ensure that property mocking remains robust and up-to-date.
+
+This decision ensures that the MiniMock framework supports a wide range of property types, providing flexibility and comprehensive mocking capabilities.
+
+---
+
+More ADRs can be found in the [docs/ADR](../README.md) directory.

docs/ADR/feature/SupportedMemberAccessLevel.md

@@ -0,0 +1,31 @@
+# Decision on Accessibility
+
+## Context
+
+The accessibility rules that applies to a manual created mock should also apply. No magic reflection logic will be done to access otherwise inaccessible members. 
+
+## Decision
+
+As such the following will be accessible.
+
+- **Virtual** and **Abstract** members must be supported. 
+- **Protected** and **Public** must be supported. 
+
+And the following will not.
+
+- **Partial**, **Sealed** and None overridable members will not be supported.
+- **Internal** and **Private** members will not be exposed. 
+
+## Consequences
+
+### Positive:
+
+- **Predictable**: Only exposes the parts of a mock that would normally be exposed.
+
+### Negative:
+
+- **Limitation**: Will not support advanced use cases.  
+
+---
+
+More ADRs can be found in the [docs/ADR](../README.md) directory.

docs/ADR/feature/TLDR.md

@@ -0,0 +1,43 @@
+# TL;DR
+
+## Summary of Decisions
+
+### Decision on Supporting Classes and Interfaces
+- **Context**: Determine the scope of support for mocking different types of members.
+- **Decision**: Primarily support interfaces but also include support for classes.
+- **Consequences**: Flexible and comprehensive but adds complexity and requires ongoing maintenance.
+
+### Decision on Accessibility
+- **Context**: Determine the accessibility rules for mocking.
+- **Decision**: Support virtual, abstract, protected, and public members. Do not support partial, sealed, non-overridable, internal, and private members.
+- **Consequences**: Predictable behaviour but limited to standard use cases.
+
+### How to Create Mocks
+- **Context**: Establish a standardized approach for creating mocks.
+- **Decision**: Use a mock factory for centralized and consistent mock creation but keep constructors accessible.
+- **Consequences**: Ensures consistency and ease of use but adds complexity and maintenance requirements.
+
+### Decision on Supporting Constructors
+- **Context**: Determine the scope of support for mocking constructors.
+- **Decision**: Support all constructors with the supported access level. If no constructor exists, create a parameterless constructor. Do not generate classes with only internal or private constructors.
+- **Consequences**: Simplifies initial implementation but limits advanced usage scenarios.
+
+### Decision on Supporting Methods
+- **Context**: Determine the scope of support for mocking methods.
+- **Decision**: Support all standard ways of creating methods, including instance, static, virtual, and abstract methods. Address support for methods returning `ref` values in future updates.
+- **Consequences**: Comprehensive and flexible but adds complexity and requires future work for `ref` values.
+
+### Decision on Supporting Properties
+- **Context**: Determine the scope of support for mocking properties.
+- **Decision**: Support mocking both read-only and read-write properties in classes and interfaces.
+- **Consequences**: Comprehensive and flexible but adds complexity and requires ongoing maintenance.
+
+### Decision on Supporting Indexers
+- **Context**: Determine the scope of support for mocking indexers.
+- **Decision**: Support mocking both read-only and read-write indexers.
+- **Consequences**: Comprehensive and flexible but adds complexity and requires ongoing maintenance.
+
+### Decision on Supporting Events
+- **Context**: Determine the scope of support for mocking events.
+- **Decision**: Support mocking all types of events, including standard, custom, and events with different delegate types.
+- **Consequences**: Comprehensive and flexible but adds complexity and requires ongoing maintenance.