Updated type constructors to indicate that they should not be called directly

docs/API.md

@@ -25,6 +25,8 @@
 ### new Operation(path, method, ptr, definition, parameters)
 The Swagger Operation object.
 
+<strong>Note:</strong> Do not use directly.
+
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -47,6 +49,8 @@ Returns all parameters for the operation.
 ### new Parameter(ptr, definition)
 The Swagger Parameter object.
 
+<strong>Note:</strong> Do not use directly.
+
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -66,6 +70,8 @@ The Swagger Parameter object.
 ### new SwaggerApi(definition, version, documentation, operations, options)
 The Swagger API object.
 
+<strong>Note:</strong> Do not use directly.
+
 
 | Param | Type | Description |
 | --- | --- | --- |
@@ -116,7 +122,7 @@ Creates a SwaggerApi object from its Swagger definition(s).
 **Example**  
 ```js
 // Example using promises
-SwaggerApi.create('http://petstore.swagger.io/v2/swagger.yaml')
+SwaggerApi.create({definition: 'http://petstore.swagger.io/v2/swagger.yaml'})
   .then(function (api) {
     console.log('Documentation URL: ', api.documentation);
   }, function (err) {
@@ -126,7 +132,7 @@ SwaggerApi.create('http://petstore.swagger.io/v2/swagger.yaml')
 **Example**  
 ```js
 // Example using callbacks
-SwaggerApi.create('http://petstore.swagger.io/v2/swagger.yaml', function (err, api) {
+SwaggerApi.create({definition: 'http://petstore.swagger.io/v2/swagger.yaml'}, function (err, api) {
   if (err) {
     console.error(err.stack);
   } else {

index.js

@@ -50,7 +50,7 @@ var supportedVersions = {
  *
  * @example
  * // Example using promises
- * SwaggerApi.create('http://petstore.swagger.io/v2/swagger.yaml')
+ * SwaggerApi.create({definition: 'http://petstore.swagger.io/v2/swagger.yaml'})
  *   .then(function (api) {
  *     console.log('Documentation URL: ', api.documentation);
  *   }, function (err) {
@@ -59,7 +59,7 @@ var supportedVersions = {
  *
  * @example
  * // Example using callbacks
- * SwaggerApi.create('http://petstore.swagger.io/v2/swagger.yaml', function (err, api) {
+ * SwaggerApi.create({definition: 'http://petstore.swagger.io/v2/swagger.yaml'}, function (err, api) {
  *   if (err) {
  *     console.error(err.stack);
  *   } else {

lib/types.js

@@ -29,6 +29,8 @@ var _ = require('lodash-compat');
 /**
  * The Swagger Operation object.
  *
+ * <strong>Note:</strong> Do not use directly.
+ *
  * @param {string} path - The operation path
  * @param {string} method - The operation method
  * @param {string} ptr - The JSON Pointer to the operation
@@ -60,6 +62,8 @@ Operation.prototype.getParameters = function () {
 /**
  * The Swagger Parameter object.
  *
+ * <strong>Note:</strong> Do not use directly.
+ *
  * @param {string} ptr - The JSON Pointer to the parameter
  * @param {object} definition - The parameter definition
  *
@@ -76,6 +80,8 @@ function Parameter (ptr, definition) {
 /**
  * The Swagger API object.
  *
+ * <strong>Note:</strong> Do not use directly.
+ *
  * @param {object} definition - The Swagger definition
  * @param {string} version - The Swagger definition version
  * @param {string} documentation - The Swagger Specification documentation URL