doc files updated

Author: begimov

docs/index.md

@@ -1,5 +1,7 @@
 # Localization Helper
 
+Package for convenient work with Laravel's localization features and fast language files generation.
+
 ## Installation
 
 Via Composer
@@ -8,17 +10,18 @@ Via Composer
 $ composer require awes-io/localization-helper
 ```
 
-In Laravel 5.5, the service provider and facade will automatically get registered. For older versions of the framework, follow the steps below:
+In Laravel 5.5+, service provider and facade will be automatically registered. For older versions, follow the steps below:
+
+Register service provider in `config/app.php`:
 
-Register the service provider in config/app.php
 ```php
 'providers' => [
 // [...]
         AwesIO\LocalizationHelper\LocalizationHelperServiceProvider::class,
 ],
 ```
 
-You may also register the LaravelLocalization facade:
+You may also register `LaravelLocalization` facade:
 
 ```php
 'aliases' => [
@@ -31,7 +34,7 @@ You may also register the LaravelLocalization facade:
 
 ### Config Files
 
-In order to edit the default configuration for this package you may execute:
+In order to edit default configuration you may execute:
 
 ```
 php artisan vendor:publish --provider="AwesIO\LocalizationHelper\LocalizationHelperServiceProvider"
@@ -41,23 +44,52 @@ After that, `config/localizationhelper.php` will be created.
 
 ## Usage
 
-Package registers global helper function:
+Package registers global helper function `_p($file_key, $default, $placeholders)`:
+
+```php
+_p('auth.login', 'Login'); // "Login"
+```
+
+It will create new localization file `auth.php` (if it doesn't exist) and write second parameter as language string under `login` key:
 
 ```php
-_p('auth.login', 'Login');
+return [
+    "login" => "Login"
+];
 ```
 
-Placeholders support:
+On second call with same file/key `_p('auth.login')`, localization string will be returned, file will remain untouched.
+
+Placeholders are also supported:
 
 ```php
 _p(
     'mail.invitation', 
     'You’re invited to join :company company workspace', 
-    ['company' => $this->data['company']]
+    ['company' => 'Awesio']
 );
 ```
 
-If key is returned, it means that string already exists and you trying to add new one using it as array.
+If key is returned, it means that string already exists in localization file and you are trying to add new one using its value as an array.
+
+```php
+// in localization file.php
+return [
+    "test" => "Test string"
+];
+
+_p('file.test.new', 'Test string'); // will return "file.test.new"
+
+_p('file.test_2.new', 'Test string'); // will return "Test string"
+
+// and modify localization file:
+return [
+    "test" => "Test string",
+    "test_2" => [
+        "new" => "Test string"
+    ]
+];
+```
 
 ## Testing
 

readme.md

@@ -2,11 +2,11 @@
 
 [![Coverage report](https://repo.pkgkit.com/4GBWO/awes-io/localization-helper/badges/master/coverage.svg)](https://www.awes.io/)
 [![Build status](https://repo.pkgkit.com/4GBWO/awes-io/localization-helper/badges/master/build.svg)](https://www.awes.io/)
-[![Composer Ready](https://www.pkgkit.com/4GBWO/awes-io/auth/status.svg)](https://www.awes.io/)
-[![Downloads](https://www.pkgkit.com/4GBWO/awes-io/auth/downloads.svg)](https://www.awes.io/)
-[![Last version](https://www.pkgkit.com/4GBWO/awes-io/auth/version.svg)](https://www.awes.io/)
+[![Composer Ready](https://www.pkgkit.com/4GBWO/awes-io/localization-helper/status.svg)](https://www.awes.io/)
+[![Downloads](https://www.pkgkit.com/4GBWO/awes-io/localization-helper/downloads.svg)](https://www.awes.io/)
+[![Last version](https://www.pkgkit.com/4GBWO/awes-io/localization-helper/version.svg)](https://www.awes.io/)
 
-Package for convenient work with Laravel's localization features. Take a look at [contributing.md](contributing.md) to see a to do list.
+Package for convenient work with Laravel's localization features and fast language files generation. Take a look at [contributing.md](contributing.md) to see a to do list.
 
 ## Installation
 
@@ -16,17 +16,18 @@ Via Composer
 $ composer require awes-io/localization-helper
 ```
 
-In Laravel 5.5, the service provider and facade will automatically get registered. For older versions of the framework, follow the steps below:
+In Laravel 5.5+, service provider and facade will be automatically registered. For older versions, follow the steps below:
+
+Register service provider in `config/app.php`:
 
-Register the service provider in config/app.php
 ```php
 'providers' => [
 // [...]
         AwesIO\LocalizationHelper\LocalizationHelperServiceProvider::class,
 ],
 ```
 
-You may also register the LaravelLocalization facade:
+You may also register `LaravelLocalization` facade:
 
 ```php
 'aliases' => [
@@ -39,7 +40,7 @@ You may also register the LaravelLocalization facade:
 
 ### Config Files
 
-In order to edit the default configuration for this package you may execute:
+In order to edit default configuration you may execute:
 
 ```
 php artisan vendor:publish --provider="AwesIO\LocalizationHelper\LocalizationHelperServiceProvider"
@@ -49,23 +50,52 @@ After that, `config/localizationhelper.php` will be created.
 
 ## Usage
 
-Package registers global helper function:
+Package registers global helper function `_p($file_key, $default, $placeholders)`:
 
 ```php
-_p('auth.login', 'Login');
+_p('auth.login', 'Login'); // "Login"
 ```
 
-Placeholders support:
+It will create new localization file `auth.php` (if it doesn't exist) and write second parameter as language string under `login` key:
+
+```php
+return [
+    "login" => "Login"
+];
+```
+
+On second call with same file/key `_p('auth.login')`, localization string will be returned, file will remain untouched.
+
+Placeholders are also supported:
 
 ```php
 _p(
     'mail.invitation', 
     'You’re invited to join :company company workspace', 
-    ['company' => $this->data['company']]
+    ['company' => 'Awesio']
 );
 ```
 
-If key is returned, it means that string already exists and you trying to add new one using it as array.
+If key is returned, it means that string already exists in localization file and you are trying to add new one using its value as an array.
+
+```php
+// in localization file.php
+return [
+    "test" => "Test string"
+];
+
+_p('file.test.new', 'Test string'); // will return "file.test.new"
+
+_p('file.test_2.new', 'Test string'); // will return "Test string"
+
+// and modify localization file:
+return [
+    "test" => "Test string",
+    "test_2" => [
+        "new" => "Test string"
+    ]
+];
+```
 
 ## Change log