Merge pull request #22 from BoBoBaSs84/docs/enrich-with-some-prose

docs: enrich with some prose

Directory.Build.props

@@ -3,7 +3,7 @@
   <PropertyGroup>
     <VersionMajor>1</VersionMajor>
     <VersionMinor>3</VersionMinor>
-    <VersionPatch>0</VersionPatch>
+    <VersionPatch>1</VersionPatch>
     <VersionPrefix>$(VersionMajor).$(VersionMinor).$(VersionPatch)</VersionPrefix>
     <VersionSuffix Condition="$(Configuration.Equals('Debug'))">Development</VersionSuffix>
   </PropertyGroup>
@@ -39,7 +39,7 @@
     <Authors>$(Author)</Authors>
     <Company>https://github.com/$(Author)</Company>
     <Copyright>Copyright © $([System.DateTime]::UtcNow.Year) $(Author)</Copyright>
-    <Description>Contains relevant things for property change/changing notification and collection change/changing notification.</Description>
+    <Description>Contains relevant things for property one-way binding / two-way binding, for property change / changing notification and for collection change / changing notification.</Description>
     <!--<PackageIcon>$(AssemblyName).png</PackageIcon>-->
     <PackageId>$(AssemblyName)</PackageId>
     <PackageTags>library;csharp;notification;common</PackageTags>

README.md

@@ -9,4 +9,75 @@
 [![License](https://img.shields.io/github/license/BoBoBaSs84/BB84.Notifications)](https://github.com/BoBoBaSs84/BB84.Notifications/blob/main/LICENSE)
 
 # BB84.Notifications
-Contains relevant things for property change/changing notification and collection change/changing notification.
+
+Contains relevant things for property one-way binding / two-way binding, for property change / changing notification and for collection change / changing notification.
+
+# Usage
+
+Depending on the application, there are several ways to skin a cat.
+
+## The bindable property class and interfaces
+
+Designed with one or two way binding in mind.
+
+```csharp
+public IBindableProperty<int> BindableInt { get; set; } = new BindableProperty<int>(default);
+```
+
+If the property is changed, the `BindablePropertyChangingEventHandler<T>` is triggered before the value changes and the `BindablePropertyChangedEventHandler<T>` is triggered after the value has changed.
+
+- The `BindablePropertyChangingEventHandler<T>` contains via the `BindablePropertyChangingEventArgs` the old value.
+- The `BindablePropertyChangedEventHandler<T>` contains via the `BindablePropertyChangedEventArgs` the new value.
+
+Further implementation possibilities can be achieved with the help of the `IBindableProperty` interface.
+
+## The notification property base class and interfaces
+
+Designed to handle changes at the class level and propagate them forward to the outside.
+
+```csharp
+public sealed class TestClass : NotifyPropertyBase
+{
+    private int _property;
+
+    public int Property
+    {
+        get => _property;
+        set => SetProperty(ref _property, value);
+    }
+}
+```
+
+If the property is changed, the `PropertyChangingEventHandler` is triggered before the value changes and the `PropertyChangedEventHandler` is triggered after the value has changed.
+
+- The `PropertyChangingEventHandler` contains via the `CollectionChangingEventArgs` the name of the property that is changing and the old value.
+- The `PropertyChangedEventHandler` contains via the `PropertyChangedEventArgs` the name of the property that has changed and the new value.
+
+Further implementation possibilities can be achieved using the `INotifyPropertyChanged` and `INotifyPropertyChanging` interfaces.
+
+## The notification collection base class and interfaces
+
+The `NotifyCollectionBase` class provides methods to handle the change within a collection and propagate it to the outside.
+
+```csharp
+public sealed class MyStringCollection : NotifyCollectionBase, ICollection<string>
+{
+  private readonly Collection<string> _collection;
+
+  public MyStringCollection()
+    => _collection = new Collection<string>();
+
+  ..
+}
+```
+
+Most of the implementation must be done despite the base class itself. The intention has been to be able to signal the state of a collection before (`CollectionChangingEventHandler`) or after (`CollectionChangedEventHandler`) the addition, deletion or modification of objects.
+
+- The `CollectionChangingEventHandler` contains via the `CollectionChangingEventArgs` the `CollectionChangeAction` and can contain the `object` before the change depending on the action.
+- The `CollectionChangedEventHandler` contains via the `CollectionChangedEventArgs` the `CollectionChangeAction` and can contain the `object` after the change depending on the action.
+
+Further implementation possibilities can be achieved with the interfaces `INotifyCollectionChanged` and `INotifyCollectionChanging`.
+
+# Documentation
+
+The API documentation can be found [here](https://bobobass84.github.io/BB84.Notifications/).

src/BB84.Notifications/Components/CollectionChangedEventArgs.cs

@@ -33,7 +33,7 @@ public CollectionChangedEventArgs(CollectionChangeAction action, object? item)
 }
 
 /// <summary>
-/// Represents the method that will handle the event of an <see cref="INotifyCollectionChanged"/> interface.
+/// Represents the method that will handle the event of the <see cref="INotifyCollectionChanged"/> interface.
 /// </summary>
 /// <param name="sender">The source of the event.</param>
 /// <param name="e">The argument that contains the event data.</param>

src/BB84.Notifications/Components/CollectionChangingEventArgs.cs

@@ -33,7 +33,7 @@ public CollectionChangingEventArgs(CollectionChangeAction action, object? item)
 }
 
 /// <summary>
-/// Represents the method that will handle the event of an <see cref="INotifyCollectionChanging"/> interface.
+/// Represents the method that will handle the event of the <see cref="INotifyCollectionChanging"/> interface.
 /// </summary>
 /// <param name="sender">The source of the event.</param>
 /// <param name="e">The argument that contains the event data.</param>

src/BB84.Notifications/Components/PropertyChangedEventArgs.cs

@@ -32,7 +32,7 @@ public PropertyChangedEventArgs(string name, object? value = null)
 }
 
 /// <summary>
-/// Represents the method that will handle the event of an <see cref="INotifyPropertyChanged"/> interface.
+/// Represents the method that will handle the event of the <see cref="INotifyPropertyChanged"/> interface.
 /// </summary>
 /// <param name="sender">The source of the event.</param>
 /// <param name="e">The argument that contains the event data.</param>

src/BB84.Notifications/Components/PropertyChangingEventArgs.cs

@@ -32,7 +32,7 @@ public PropertyChangingEventArgs(string name, object? value = null)
 }
 
 /// <summary>
-/// Represents the method that will handle the event of an <see cref="INotifyPropertyChanging"/> interface.
+/// Represents the method that will handle the event of the <see cref="INotifyPropertyChanging"/> interface.
 /// </summary>
 /// <param name="sender">The source of the event.</param>
 /// <param name="e">The argument that contains the event data.</param>