From 64fe9d3e49f2fbc386c75644fe97262ec34dd718 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Fran=C3=A7ois=20de=20Metz?= <francois@2metz.fr>
Date: Mon, 30 Jul 2018 09:45:56 +0200
Subject: [PATCH] Update readme with clear sections.

---
 README.md | 81 +++++++++++++++++++++++++++++++++----------------------
 1 file changed, 49 insertions(+), 32 deletions(-)

diff --git a/README.md b/README.md
index 032b124..db007be 100644
--- a/README.md
+++ b/README.md
@@ -10,48 +10,65 @@ Install via bundler
 
 ## Usage
 
+## Authentication
+
+The easiest way to configure the authentication is to set the API key globally. You can also set it on each request.
+
 ```ruby
 require 'cleantalk'
 
-# Create a check_newuser request
-request = Cleantalk::CheckNewuser.new({ auth_key: 'ur_api_key', sender_email: 'test@example.org' }) # Can initialize with values
-request.sender_ip       = '127.0.0.1' # and also mutate object directly
-request.sender_nickname = 'test nickname'
-request.js_on           = 1 # you should check for JavaScript by yourself
-request.submit_time     = 11 # you should calculate time for submitting form by youself
+Cleantalk.auth_key = 'ur_api_key'
+```
 
-request.allowed? # => true or false
-request.result   # => <Object Cleantalk::CheckNewuserResult> with all response data
+## Check user registration
 
-# Create a check_message request
-request = Cleantalk::CheckMessage.new({
-  auth_key: 'ur_api_key', sender_email: 'test@example.org',
-  sender_ip: '127.0.0.1', sender_nickname: 'test nickname',
-  js_on: 1, submit_time: 11
-}) # Can initialize with values
-request.message = '<p>Hello World!</p>'  # and also mutate object directly
+See https://cleantalk.org/help/api-check-newuser
+
+```ruby
+require 'cleantalk'
+
+request = Cleantalk::CheckNewuser.new({
+  auth_key: 'ur_api_key',            # Required if not defined via Cleantalk.auth_key. the API Key
+  sender_email: 'test@example.org',  # Required: The email used by the user
+  sender_ip: '127.0.0.1',            # Required: The IP used by the user
+  js_on: 1,                          # Required: 1 if the user has javascript enabled, 0 otherwise
+  submit_time: 11,                   # Required: Time spend you submit the request in seconds
+  sender_nickname: 'test nickname',  # Optional: The nickname used by the user
+})
 
 request.allowed? # => true or false
-request.result   # => <Object Cleantalk::CheckMessageResult> with all response data
+request.result   # => <Object Cleantalk::CheckNewuserResult> with all response data
+```
 
-# You can also pass auth_key has global configuration (still overridable by passing auth_key to request):
-Cleantalk.auth_key = 'ur_api_key'
+Depending of your use case, you can also mutate the request:
 
-# Create a legacy request instance
-request = Cleantalk::Request.new
-request.auth_key        = 'your_key'
-request.message         = 'test message' # don't use this field for registration check
-request.sender_email    = 'stop_email@example.com'
-request.sender_nickname = 'test nickname'
+```ruby
+require 'cleantalk'
+
+request = Cleantalk::CheckNewuser.new({ auth_key: 'ur_api_key', sender_email: 'test@example.org' })
 request.sender_ip       = '127.0.0.1'
-request.js_on           = 1 # you should check for JavaScript by yourself
-request.submit_time     = 11 # you should calculate time for submitting form by youself
-request.sender_info     = {cms_lang: 'en_US'} # here put locale for your language
+request.sender_nickname = 'test nickname'
+request.js_on           = 1
+request.submit_time     = 11
+```
+
+## Check message
 
-cleantalk = Cleantalk.new
-result = cleantalk.is_allowed_message(request) # for message checking
-result = cleantalk.is_allowed_user(request)    # for registration checking
+See https://cleantalk.org/help/api-check-message
 
-# result['allow'] contains our decision: 1 for allowed message, 0 for blocked
-# result['comment'] contains comment for our decision
+```ruby
+require 'cleantalk'
+
+request = Cleantalk::CheckMessage.new({
+  auth_key: 'ur_api_key',           # Required if not defined via Cleantalk.auth_key. the API Key
+  sender_email: 'test@example.org', # Required: The email used by the user
+  sender_ip: '127.0.0.1',           # Required: The IP used by the user
+  js_on: 1,                         # Required: 1 if the user has javascript enabled, 0 otherwise
+  submit_time: 11,                  # Required: Time spend you submit the request in seconds
+  message: '<p>Hello World!</p>'    # Required: The text of the message
+  sender_nickname: 'test nickname', # Optional: The nickname used by the user
+})
+
+request.allowed? # => true or false
+request.result   # => <Object Cleantalk::CheckMessageResult> with all response data
 ```