Update documentation for new objects

Author: Kevin Paulisse

doc/dev/api/v1.md

@@ -1,19 +1,35 @@
 # octocatalog-diff v1 API documentation
 
-## catalog
+## API calls
+
+#### catalog
 
 `catalog` allows you to build a catalog using the octocatalog-diff compiler or to obtain a catalog from a Puppet server.
 
-[Read more about `catalog`](/doc/dev/api/v1/catalog.md)
+[Read more about the `catalog` call](/doc/dev/api/v1/calls/catalog.md)
 
-## catalog-diff
+#### catalog-diff
 
 `catalog-diff` allows you compare two catalogs and obtain the differences between them. Catalogs can be built if necessary.
 
-[Read more about `catalog-diff`](/doc/dev/api/v1/catalog-diff.md)
+[Read more about the `catalog-diff` call](/doc/dev/api/v1/calls/catalog-diff.md)
 
-## config
+#### config
 
 `config` allows you read and parse an [octocatalog-diff configuration file](/doc/configuration.md).
 
-[Read more about `config`](/doc/dev/api/v1/config)
+[Read more about the `config` call](/doc/dev/api/v1/calls/config.md)
+
+## Objects
+
+#### OctocatalogDiff::API::V1::Catalog
+
+The `OctocatalogDiff::API::V1::Catalog` object represents a compiled catalog and supports several methods to get information about the catalog.
+
+[Read more about the `OctocatalogDiff::API::V1::Catalog` object](/doc/dev/api/v1/objects/catalog.md)
+
+#### OctocatalogDiff::API::V1::Diff
+
+The `OctocatalogDiff::API::V1::Diff` object represents a difference between two catalogs and supports several methods to get information about the difference.
+
+[Read more about the `OctocatalogDiff::API::V1::Diff` object](/doc/dev/api/v1/objects/diff.md)

doc/dev/api/v1/catalog-diff.md doc/dev/api/v1/calls/catalog-diff.mddoc/dev/api/v1/catalog-diff.md renamed to doc/dev/api/v1/calls/catalog-diff.md

@@ -18,4 +18,20 @@ catalog_diff_result = OctocatalogDiff::API::V1.catalog_diff(
 
 ## Return value
 
+The return value is a structure in the following format:
+
+```
+{
+  diffs: Array<OctocatalogDiff::API::V1::Diff>,
+  from: OctocatalogDiff::API::V1::Catalog,
+  to: OctocatalogDiff::API::V1::Catalog
+}
+```
+
+It is possible to query this object as a hash (e.g. `result[:diffs]`) or using methods (e.g. `result.diffs`).
+
+[Read more about the `OctocatalogDiff::API::V1::Catalog` object](/doc/dev/api/v1/objects/catalog.md)
+
+[Read more about the `OctocatalogDiff::API::V1::Diff` object](/doc/dev/api/v1/objects/diff.md)
+
 ## Exceptions

doc/dev/api/v1/catalog.md doc/dev/api/v1/calls/catalog.mddoc/dev/api/v1/catalog.md renamed to doc/dev/api/v1/calls/catalog.md

@@ -17,6 +17,6 @@ catalog_obj = OctocatalogDiff::API::V1.catalog(
 
 ## Return value
 
-The return value is an [`OctocatalogDiff::Catalog`](/doc/dev/api/v1/octocatalogdiff-catalog.md) object.
+The return value is an [`OctocatalogDiff::API::V1::Catalog`](/doc/dev/api/v1/objects/catalog.md) object.
 
 ## Exceptions

doc/dev/api/v1/config.md doc/dev/api/v1/calls/config.mddoc/dev/api/v1/config.md renamed to doc/dev/api/v1/calls/config.md

@@ -0,0 +1,13 @@
+# octocatalog-diff v1 API documentation: OctocatalogDiff::API::V1::Catalog
+
+## Overview
+
+`OctocatalogDiff::API::V1::Catalog` is an object that represents a compiled catalog.
+
+It wraps the [`OctocatalogDiff::Catalog`](/lib/octocatalog-diff/catalog.rb) object.
+
+This object is the return value from the [`catalog`](/doc/dev/api/v1/calls/catalog.md) API call, and the `to` and `from` catalogs computed by the [`catalog-diff`](/doc/dev/api/v1/calls/catalog-diff.md) API call.
+
+## Methods
+
+## Exceptions

doc/dev/api/v1/objects/catalog.md

@@ -0,0 +1,11 @@
+# octocatalog-diff v1 API documentation: OctocatalogDiff::API::V1::Diff
+
+## Overview
+
+`OctocatalogDiff::API::V1::Diff` is an object that represents a single difference between two catalogs.
+
+The return value from the `diffs` computed by the [`catalog-diff`](/doc/dev/api/v1/calls/catalog-diff.md) API call is an Array of these `OctocatalogDiff::API::V1::Diff` objects.
+
+## Methods
+
+## Exceptions