Enhance documentation (#337)

* Add description to the configurations in README

* Make it clear that this is a description of custom rules in README

* Describe the feature to suggest fixes in README

* Correct type of code snippet

* Make it clear that 'singular' is the default setting in name-inflection

* Add configuration snippets to the README of built-in rules

* Add detailed instruction of the custom rules to the example/README

README.md

@@ -4,10 +4,13 @@ Run linting rules on your database schema. Read the intro to this idea in [this
 
 _Works with Postgres databases._
 
-This will give you errors like these:
+This will give you errors and suggestions like these:
 
 ```
 public.actor.first_name: error prefer-text-to-varchar : Prefer text to varchar types
+
+Suggested fix
+ALTER TABLE "public"."actor" ALTER COLUMN "first_name" TYPE TEXT;
 ```
 
 ## Usage
@@ -28,6 +31,7 @@ Here is an example configuration file:
 
 ```javascript
 module.exports = {
+  // Connection configuration. See: https://node-postgres.com/apis/client
   connection: {
     host: "localhost",
     user: "postgres",
@@ -36,26 +40,37 @@ module.exports = {
     charset: "utf8",
   },
 
-  plugins: ["./custom-rules"],
+  // Schemas to lint.
+  schemas: [{ name: "public" }],
 
+  // Rules to be checked. The key is the rule name and the value is an array
+  // whose first value is the severity (only "error" is supported) and the
+  // rest are rule-specific parameters.
   rules: {
     "name-casing": ["error", "snake"],
     "name-inflection": ["error", "singular"],
     "prefer-jsonb-to-json": ["error"],
     "prefer-text-to-varchar": ["error"],
   },
 
-  schemas: [{ name: "public" }],
-
+  // (Optional) Use the `ignores` array to exclude specific targets and
+  // rules. The targets are identified by the `identifier` (exact) or the
+  // `identifierPattern` (regex). For the rules, use the `rule` (exact) or
+  // the `rulePattern` (regex).
   ignores: [
+    { identifier: "public.sessions", rule: "name-inflection" },
     { identifierPattern: "public\\.knex_migrations.*", rulePattern: ".*" },
   ],
+
+  // (Optional)　Use the `plugins` array to load custom rules. The paths are
+  // `require`d as Node.js modules from the current working directory.
+  plugins: ["./custom-rules"],
 };
 ```
 
 ## Rules
 
-Schemalint includes a number of built-in rules, which you can read about [here](/src/rules). However, writing rules is easy and you will probably see the real value by doing so. The [example](/example) folder shows how to write these.
+Schemalint includes a number of built-in rules, which you can read about [here](/src/rules). However, writing custom rules is easy and you will probably see the real value by doing so. The [example](/example) folder shows how to write these.
 
 ## Sponsors
 

example/README.md

@@ -1,5 +1,9 @@
 # Example
 
+This folder contains an example configuration file and custom rules for Schemalint.
+
+## Usage
+
 If you want to try this, you can run it on the [Sample Database](https://www.postgresqltutorial.com/postgresql-sample-database/) from www.postgresqltutorial.com.
 
 I've created a Docker image that hosts it so if you have Docker installed, you can easily set up such a database locally by running
@@ -63,3 +67,12 @@ error Command failed with exit code 1.
 ```
 
 You can play around with the configuration options in `.schemalintrc.js` file to experiment.
+
+## Custom Rules
+
+Example custom rules are included in the [custom-rules](./custom-rules) folder. The folder contains the following files:
+
+- [identifierNaming.js](./custom-rules/identifierNaming.js): Defines the custom rule `identifier-naming`.
+- [index.js](./custom-rules/index.js): Exports the custom rules.
+
+You can use these as a starting point to create your own custom rules. The type definition of the [Rule](/src/Rule.ts) object and the [Schema](https://kristiandupont.github.io/extract-pg-schema/api/extract-pg-schema.schema.html) object passed to the custom rules will help you understand how to write custom rules.

src/rules/README.md

@@ -12,22 +12,46 @@ If, for some reason or other, you want to use a different naming scheme, you can
 
 At the moment, this rule checks tables, views and columns.
 
+```js
+  rules: {
+    'name-casing': ['error', 'snake'],
+  },
+```
+
 ## prefer-text-to-varchar
 
 In Postgres there is no performance penalty on using the `text` type which has no maximum length, so you will generally want to choose that over `varchar`.
 The reasoning for this is outlined in the Postgres wiki: [Don't use varchar(n) by default](https://wiki.postgresql.org/wiki/Don't_Do_This#Don.27t_use_varchar.28n.29_by_default)
 
+```js
+  rules: {
+    'prefer-text-to-varchar': ['error'],
+  },
+```
+
 ## name-inflection
 
 If you want to enforce singular or plural naming for your tables, this rule can enforce it.
-Which one to choose is a matter of great debate but in the end it comes down to personal preference. You can choose `'singular'` or `'plural'`.
+Which one to choose is a matter of great debate but in the end it comes down to personal preference. You can choose `'singular'` (default) or `'plural'`.
+
+```js
+  rules: {
+    'name-inflection': ['error', 'singular'],
+  },
+```
 
 ## prefer-timestamptz-to-timestamp
 
 In Postgres when you insert a value into a `timestamptz` column, PostgreSQL converts the `timestamptz` value into a UTC value and stores the UTC value in the table, and when you query `timestamptz`
 from the database, PostgreSQL converts the UTC value back to the time value of the timezone set by the database server, the user, or the current database connection, whereas `timestamp` does not save any
 timezone data. You can learn more here: [Understanding PostgreSQL Timestamp Data Types](https://www.postgresqltutorial.com/postgresql-timestamp/)
 
+```js
+  rules: {
+    'prefer-timestamptz-to-timestamp': ['error'],
+  },
+```
+
 ## prefer-jsonb-to-json
 
 `json` data is stored as a copy of the input text which processing functions need to reparse on each execution. `jsonb` data is stored in a binary format which is faster to process, and also supports indexing.
@@ -38,6 +62,12 @@ While there are some caveats, the official PostgreSQL documentation states:
 
 You can learn more here: [JSON types](https://www.postgresql.org/docs/current/datatype-json.html)
 
+```js
+  rules: {
+    'prefer-jsonb-to-json': ['error'],
+  },
+```
+
 ## prefer-identity-to-serial
 
 Identity columns are a SQL standard-conforming variant of PostgreSQL's serial columns. They fix a few usability
@@ -51,11 +81,17 @@ issues that serial columns have:
 
 You can learn more here: [Identity Columns Explained](https://www.2ndquadrant.com/en/blog/postgresql-10-identity-columns/)
 
+```js
+  rules: {
+    'prefer-identity-to-serial': ['error'],
+  },
+```
+
 ## require-primary-key
 
 Identity tables that do not have a primary key defined. Tables can be ignored by passing the `ignorePattern` rule argument.
 
-```json
+```js
  rules: {
     'require-primary-key': ['error', {
       ignorePattern: 'information_schema.*'