Clarify the meaning of schema, closes #1908

lib/sequelize.js

@@ -492,7 +492,12 @@ module.exports = (function() {
   };
   };
 
 
   /**
   /**
-   * Create a new database schema
+   * Create a new database schema.
+   *
+   * Note,that this is a schema in the [postgres sense of the word](http://www.postgresql.org/docs/9.1/static/ddl-schemas.html),
+   * not a database table. In mysql and sqlite, this command will do nothing.
+   * 
+   * @see {Model#schema}
    * @param {String} schema Name of the schema
    * @param {String} schema Name of the schema
    * @return {Promise}
    * @return {Promise}
    */
    */
@@ -502,6 +507,9 @@ module.exports = (function() {
 
 
   /**
   /**
    * Show all defined schemas
    * Show all defined schemas
+   * 
+   * Note,that this is a schema in the [postgres sense of the word](http://www.postgresql.org/docs/9.1/static/ddl-schemas.html),
+   * not a database table. In mysql and sqlite, this will show all tables.
    * @return {Promise}
    * @return {Promise}
    */
    */
   Sequelize.prototype.showAllSchemas = function() {
   Sequelize.prototype.showAllSchemas = function() {
@@ -510,6 +518,9 @@ module.exports = (function() {
 
 
   /**
   /**
    * Drop a single schema
    * Drop a single schema
+   *
+   * Note,that this is a schema in the [postgres sense of the word](http://www.postgresql.org/docs/9.1/static/ddl-schemas.html),
+   * not a database table. In mysql and sqlite, this drop a table matching the schema name
    * @param {String} schema Name of the schema
    * @param {String} schema Name of the schema
    * @return {Promise}
    * @return {Promise}
    */
    */
@@ -519,6 +530,9 @@ module.exports = (function() {
 
 
   /**
   /**
    * Drop all schemas
    * Drop all schemas
+   *
+   * Note,that this is a schema in the [postgres sense of the word](http://www.postgresql.org/docs/9.1/static/ddl-schemas.html),
+   * not a database table. In mysql and sqlite, this is the equivalent of drop all tables.
    * @return {Promise}
    * @return {Promise}
    */
    */
   Sequelize.prototype.dropAllSchemas = function() {
   Sequelize.prototype.dropAllSchemas = function() {