update documentation

Author: darkv

README.md

@@ -79,9 +79,6 @@ Optionally you can specify *wordCacheFile* to control the location and name of t
 
 To a custom instance you can pass an optional boolean parameter *fetch*. When false, the cached wordlist will be preferred but falls back to fetching if it could not be loaded.
 
-You can also mix different RSS sources into the same wordlist file with the `appendWordlist` parameter, increasing entropy, or regularly rebuild your cache file from time to time to feed it with new words. Altought having more words is always desirable,
-you can limit the number of items in the wordlist with the `limitWordlist` configuration parameter. When using append, wordlist is shuffled before being limited to the desired quantity.
-
 ```php
 include 'PasswordGenerator.php';
 
@@ -93,8 +90,16 @@ $gen = PasswordGenerator::EN();
 echo 'Password 1: ', $gen->generate();
 echo 'Password 2: ', $gen->generate();
 echo 'Password 3: ', $gen->generate();
+```
+
+When fetching an RSS source the normal behaviour is to create a new list, overwriting an existing cache file. You can opt-in to merge the new wordlist with an exisiting cache file instead, by setting the `appendWordlist` parameter to true. On the one hand this will result in bigger word lists, increasing entropy, on the other hand this may lead to very long lists. You can limit the number of items in the wordlist with the `limitWordlist` configuration parameter. When using this option and the wordlist is exceeding that limit, it is shuffled and then sliced to that number.
+
+```php
+include 'PasswordGenerator.php';
+
+use \Darkv\PhpPasswordGenerator\PasswordGenerator;
 
-// Append NYTimes feed to the specified wordlist, limiting to 7000 items max
+// append NYTimes feed to the specified wordlist, limiting to 7000 items max
 $gen = new PasswordGenerator([
     'wordCacheFile'  => 'mywords.json',
     'url'            => 'https://rss.nytimes.com/services/xml/rss/nyt/World.xml',
@@ -170,11 +175,11 @@ When creating an instance of PasswordGenerator you can provide the following par
 
 * **appendWordlist**
 
-  If true, the fetched wordlist will be appended to the current one. If false, wordlist is generated from scratch.
+  If true, the fetched wordlist will be appended to an existing cache file. If false, cache will be overwritten.
 
 * **limitWordlist**
 
-  Int value declaring the maximum words the wordlist must contain. Useful when using appendWordList.
+  Int value declaring the maximum number if words the wordlist may contain. Useful when using appendWordList.
 
 
 ## License

example/PasswordGenerator.example.php

@@ -52,7 +52,7 @@
 // generate a password with custom pattern
 echo $gen->generate('wiwsw'), "\n";
 
-// Append NYTimes feed to the last wordlist, limiting to 700 items max
+// append NYTimes feed to the existing cache file, limiting to 700 items max
 $gen = new PasswordGenerator([
     'wordCacheFile'  => 'mywords.json',
     'url'            => 'https://rss.nytimes.com/services/xml/rss/nyt/World.xml',

src/PasswordGenerator.php

@@ -72,9 +72,11 @@ class PasswordGenerator
      *   <dt>wordCacheFile</dt>
      *   <dd>Filename of the cache file.</dd>
      *   <dt>appendWordlist</dt>
-     *   <dd>If true, the fetched wordlist will be appended to the current one. If false, wordlist is generated from scratch.</dd>
+     *   <dd>If true, the fetched wordlist will be appended to the an existing
+     *   one. If false, wordlist is generated from scratch.</dd>
      *   <dt>limitWordlist</dt>
-     *   <dd>Int value declaring the maximum words the wordlist must contain. Useful when using appendWordList.</dd>
+     *   <dd>Int value declaring the maximum number of words the wordlist may
+     *   contain. Useful when using appendWordList.</dd>
      *   <dt>httpRedirects</dt>
      *   <dd>Number of maximum HTTP redirects the script will follow.</dd>
      * </dl>