Merge branch 'master' of github.com:nilportugues/sql-query-builder

Author: nilportugues

README.md

@@ -1,7 +1,7 @@
 SQL Query Builder
 =================
 
-[![Build Status](https://travis-ci.org/nilportugues/sql-query-builder.png)](https://travis-ci.org/nilportugues/sql-query-builder) [![Coverage Status](https://img.shields.io/coveralls/nilportugues/sql-query-builder.svg)](https://coveralls.io/r/nilportugues/sql-query-builder) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/nilportugues/sql-query-builder/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/nilportugues/sql-query-builder/?branch=master)  [![SensioLabsInsight](https://insight.sensiolabs.com/projects/89ec1003-4227-43a2-8432-67a9fc2d3ba3/mini.png)](https://insight.sensiolabs.com/projects/89ec1003-4227-43a2-8432-67a9fc2d3ba3) [![Latest Stable Version](https://poser.pugx.org/nilportugues/sql-query-builder/v/stable.svg)](https://packagist.org/packages/nilportugues/sql-query-builder) [![Total Downloads](https://poser.pugx.org/nilportugues/sql-query-builder/downloads.svg)](https://packagist.org/packages/nilportugues/sql-query-builder) [![License](https://poser.pugx.org/nilportugues/sql-query-builder/license.svg)](https://packagist.org/packages/nilportugues/sql-query-builder)
+[![Build Status](https://travis-ci.org/nilportugues/sql-query-builder.svg)](https://travis-ci.org/nilportugues/sql-query-builder) [![Coverage Status](https://img.shields.io/coveralls/nilportugues/sql-query-builder.svg)](https://coveralls.io/r/nilportugues/sql-query-builder) [![Scrutinizer Code Quality](https://scrutinizer-ci.com/g/nilportugues/sql-query-builder/badges/quality-score.png?b=master)](https://scrutinizer-ci.com/g/nilportugues/sql-query-builder/?branch=master)  [![SensioLabsInsight](https://insight.sensiolabs.com/projects/89ec1003-4227-43a2-8432-67a9fc2d3ba3/mini.png)](https://insight.sensiolabs.com/projects/89ec1003-4227-43a2-8432-67a9fc2d3ba3) [![Latest Stable Version](https://poser.pugx.org/nilportugues/sql-query-builder/v/stable)](https://packagist.org/packages/nilportugues/sql-query-builder) [![Total Downloads](https://poser.pugx.org/nilportugues/sql-query-builder/downloads)](https://packagist.org/packages/nilportugues/sql-query-builder) [![License](https://poser.pugx.org/nilportugues/sql-query-builder/license)](https://packagist.org/packages/nilportugues/sql-query-builder)
 
 An elegant lightweight and efficient SQL Query Builder with fluid interface SQL syntax supporting bindings and complicated query generation.
 <a name="index_block"></a>
@@ -42,9 +42,10 @@ An elegant lightweight and efficient SQL Query Builder with fluid interface SQL
     * [4.5. Columns as SELECT statements](#block4.5)        
     * [4.6. Columns being Values](#block4.6)
     * [4.7. Columns using FUNCTIONS](#block4.7)
-* [5. Quality Code](#block5)
-* [6. Author](#block6)
-* [7. License](#block7)
+* [5. Commenting queries](#block5)
+* [6. Quality Code](#block6)
+* [7. Author](#block7)
+* [8. License](#block8)
 
 
 <a name="block1"></a>
@@ -120,8 +121,7 @@ use NilPortugues\Sql\QueryBuilder\Builder\GenericBuilder;
 
 $builder = new GenericBuilder(); 
 
-$query = $builder->select()->setTable('user');    
-$builder = new GenericBuilder();    
+$query = $builder->select()->setTable('user');  
 
 echo $builder->writeFormatted($query);    
 
@@ -1068,10 +1068,37 @@ WHERE
     (user.user_id = :v1)
 ```
 
+<a name="block5"></a>
+## 5. Commenting queries [↑](#index_block)
+The query builder allows adding comments to all query methods by using the `setComment` method.
+
+Some useful use cases examples can be : 
 
+ - Explain difficult queries or why of its existence. 
+ - Finding slow queries from its comments.
 
-<a name="block5"></a>
-## 5. Quality Code [↑](#index_block)
+#### Usage:
+```php
+<?php
+use NilPortugues\Sql\QueryBuilder\Builder\GenericBuilder;
+
+$builder = new GenericBuilder(); 
+
+$query = $builder->select()
+    ->setTable('user')
+    ->setComment('This is a comment');
+    
+$sql = $builder->write($query);   
+```
+
+#### Output:
+```sql
+-- This is a comment
+SELECT user.* FROM user
+```
+
+<a name="block6"></a>
+## 6. Quality Code [↑](#index_block)
 Testing has been done using PHPUnit and [Travis-CI](https://travis-ci.org). All code has been tested to be compatible from PHP 5.4 up to PHP 5.6 and [HHVM](http://hhvm.com/).
 
 To run the test suite, you need [Composer](http://getcomposer.org):
@@ -1082,16 +1109,16 @@ To run the test suite, you need [Composer](http://getcomposer.org):
 ```
 
 
-<a name="block6"></a>
-## 6. Author [↑](#index_block)
+<a name="block7"></a>
+## 7. Author [↑](#index_block)
 Nil Portugués Calderó
 
  - <[email protected]>
  - [http://nilportugues.com](http://nilportugues.com)
 
 
-<a name="block7"></a>
-## 7. License [↑](#index_block)
+<a name="block8"></a>
+## 8. License [↑](#index_block)
 SQL Query Builder is licensed under the MIT license.
 
 ```