Merge pull request #64 from gobuffalo/update-readme

updated README and SHOULDERS

README.md

@@ -1,24 +1,53 @@
 # Flect
 
-<p align="center">
-<a href="https://godoc.org/github.com/gobuffalo/flect"><img src="https://godoc.org/github.com/gobuffalo/flect?status.svg" alt="GoDoc" /></a>
-<a href="https://goreportcard.com/report/github.com/gobuffalo/flect"><img src="https://goreportcard.com/badge/github.com/gobuffalo/flect" alt="Go Report Card" /></a>
-</p>
+[![Go Reference](https://pkg.go.dev/badge/github.com/gobuffalo/flect.svg)](https://pkg.go.dev/github.com/gobuffalo/flect)
+[![Standard Test](https://github.com/gobuffalo/flect/actions/workflows/standard-go-test.yml/badge.svg)](https://github.com/gobuffalo/flect/actions/workflows/standard-go-test.yml)
+[![Go Report Card](https://goreportcard.com/badge/github.com/gobuffalo/flect)](https://goreportcard.com/report/github.com/gobuffalo/flect)
 
 This is a new inflection engine to replace [https://github.com/markbates/inflect](https://github.com/markbates/inflect) designed to be more modular, more readable, and easier to fix issues on than the original.
 
+Flect provides word inflection features such as `Singularize` and `Pluralize`
+for English nouns and text utility features such as `Camelize`, `Capitalize`,
+`Humanize`, and more.
+
+Due to the flexibly-complex nature of English noun inflection, it is almost
+impossible to cover all exceptions (such as identical/irregular plural).
+With this reason along with the main purpose of Flect, which is to make it
+easy to develop web application in Go, Flect has limitations with its own
+rules.
+
+* It covers regular rule (adding -s or -es and of the word)
+* It covers well-known irregular rules (such as -is to -es, -f to -ves, etc)
+  * https://en.wiktionary.org/wiki/Appendix:English_irregular_nouns#Rules
+* It covers well-known irregular words (such as children, men, etc)
+* If a word can be countable and uncountable like milk or time, it will be
+  treated as countable.
+* If a word has more than one plural forms, which means it has at least one
+  irregular plural, we tried to find most popular one. (The selected plural
+  could be odd to you, please feel free to open an issue with back data)
+  * For example, we selected "stadiums" over "stadia", "dwarfs" over "dwarves"
+  * One or combination of en.wiktionary.org, britannica.com, and
+    trends.google.com are used to check the recent usage trends.
+* However, we cannot cover all cases and some of our cases could not fit with
+  your situation. You can override the default with functions such as
+  `InsertPlural()`, `InsertSingular()`, or `LoadInfrections()`.
+* If you have a json file named `inflections.json` in your application root,
+  the file will be automatically loaded as your custom inflection dictionary.
+
 ## Installation
 
-```bash
-$ go get -u -v github.com/gobuffalo/flect
+```console
+$ go get github.com/gobuffalo/flect
 ```
 
-## `github.com/gobuffalo/flect`
-<a href="https://godoc.org/github.com/gobuffalo/flect"><img src="https://godoc.org/github.com/gobuffalo/flect?status.svg" alt="GoDoc" /></a>
+
+## Packages
+
+### `github.com/gobuffalo/flect`
 
 The `github.com/gobuffalo/flect` package contains "basic" inflection tools, like pluralization, singularization, etc...
 
-### The `Ident` Type
+#### The `Ident` Type
 
 In addition to helpful methods that take in a `string` and return a `string`, there is an `Ident` type that can be used to create new, custom, inflection rules.
 
@@ -29,7 +58,6 @@ The `Ident` type contains two fields.
 
 Examples of creating new inflection rules using `Ident` can be found in the `github.com/gobuffalo/flect/name` package.
 
-## `github.com/gobuffalo/flect/name`
-<a href="https://godoc.org/github.com/gobuffalo/flect/name"><img src="https://godoc.org/github.com/gobuffalo/flect/name?status.svg" alt="GoDoc" /></a>
+### `github.com/gobuffalo/flect/name`
 
 The `github.com/gobuffalo/flect/name` package contains more "business" inflection rules like creating proper names, table names, etc...

SHOULDERS.md

@@ -1,10 +1,12 @@
-# github.com/gobuffalo/flect Stands on the Shoulders of Giants
+# Flect Stands on the Shoulders of Giants
 
-github.com/gobuffalo/flect does not try to reinvent the wheel! Instead, it uses the already great wheels developed by the Go community and puts them all together in the best way possible. Without these giants, this project would not be possible. Please make sure to check them out and thank them for all of their hard work.
+Flect does not try to reinvent the wheel! Instead, it uses the already great wheels developed by the Go community and puts them all together in the best way possible. Without these giants, this project would not be possible. Please make sure to check them out and thank them for all of their hard work.
 
 Thank you to the following **GIANTS**:
 
-
 * [github.com/davecgh/go-spew](https://godoc.org/github.com/davecgh/go-spew)
-
+* [github.com/pmezard/go-difflib](https://godoc.org/github.com/pmezard/go-difflib)
+* [github.com/stretchr/objx](https://godoc.org/github.com/stretchr/objx)
 * [github.com/stretchr/testify](https://godoc.org/github.com/stretchr/testify)
+* [gopkg.in/check.v1](https://godoc.org/gopkg.in/check.v1)
+* [gopkg.in/yaml.v3](https://godoc.org/gopkg.in/yaml.v3)