docs: Add README documentation for matchers

README.md

@@ -16,10 +16,119 @@
 ## Menu
 
 - [Menu](#menu)
+- [Why ?](#why-)
+- [How to use ?](#how-to-use-)
+- [Matchers](#matchers)
+  - [IntRangeMatcher](#intrangematcher)
+    - [Explanation](#explanation)
+    - [Example](#example)
+  - [StringRegexpMatcher](#stringregexpmatcher)
+    - [Explanation](#explanation-1)
+    - [Example](#example-1)
+  - [MapMatcher](#mapmatcher)
+    - [Explanation](#explanation-2)
+    - [Example](#example-2)
+  - [StructMatcher](#structmatcher)
+    - [Explanation](#explanation-3)
+    - [Example](#example-3)
 - [Thanks](#thanks)
 - [Author](#author)
 - [License](#license)
 
+## Why ?
+
+I've created this library because I cannot find such a library like this one and I don't want to create specific matcher for each structure, each map, ... in all tests that I have and can write.
+
+Moreover, creating specific matcher need maintenance code and this is time consumption.
+
+I'm sure that I'm not the only one that what to avoid all of this :) .
+
+## How to use ?
+
+Import the library in your tests files:
+
+```go
+import "github.com/oxyno-zeta/gomock-extra-matcher"
+```
+
+Use it in your gomock instance:
+
+```go
+mock.EXPECT().DoSomething(extra.StringRegexpMatcher(`^[a-z]+\[[0-9]+\]$`))
+```
+
+## Matchers
+
+### IntRangeMatcher
+
+#### Explanation
+
+This matcher will allow to test that an int is inside a range. Here it is considered that input can be equal to the lower bound and the same for the upper bound.
+
+#### Example
+
+Here is an example of usage:
+
+```go
+mock.EXPECT().DoSomething(extra.IntRangeMatcher(lowerBound, upperBound))
+```
+
+### StringRegexpMatcher
+
+#### Explanation
+
+This matcher will allow to test that a string is validating a Regexp.
+
+#### Example
+
+Here is an example of usage:
+
+```go
+mock.EXPECT().DoSomething(extra.StringRegexpMatcher(`^[a-z]+\[[0-9]+\]$`))
+```
+
+### MapMatcher
+
+#### Explanation
+
+This matcher will allow to test map key and map value.
+
+To this one, it is possible to give a gomock matcher to a key and also to the value.
+
+The `Key` function is chainable. It is also possible to more than one test per key.
+
+#### Example
+
+Here are some example of usage:
+
+```go
+// Here we consider a map[string]string as input
+mock.EXPECT().DoSomething(extra.MapMatcher().Key("key1", "value1").Key(gomock.Any(), "value1").Key("key1", gomock.Not("value2")))
+```
+
+### StructMatcher
+
+#### Explanation
+
+This matcher will allow to test public fields of a structure (Only public ones. Reflect can't manage private fields...).
+
+To this matcher, it is possible to give either a gomock matcher or either a real value for validation.
+
+The `Field` function is chainable. It is also possible to more than one test per field.
+
+#### Example
+
+```go
+// Here we consider a struct as this one
+/*
+type Fake struct {
+    Name string
+    Data map[string]string
+}
+*/
+mock.EXPECT().DoSomething(extra.MapMatcher().Field("Name", "value1").Field("Data", gomock.Eq(map[string]string{"fake":"value"})))
+```
+
 ## Thanks
 
 - My wife BH to support me doing this