Add documentation and test for structure

Author: Kevin Paulisse

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

@@ -24,8 +24,86 @@ Returns the change type of the diff, which is one of the following characters:
 - `-` for removal (resource exists in old catalog but not new catalog)
 - `~` or `!` for change (resource exists in both catalogs but is different between them)
 
+See also: `#addition?`, `#change?`, `#removal?`
+
 Note: Internally `~` and `!` represent different types of changes, but when presenting the output, these can generally be considered equivalent.
 
-#### `removal?` (Boolean)
+#### `#removal?` (Boolean)
 
 Returns true if this diff is a removal (resource exists in old catalog but not new catalog).
+
+#### `#structure` (Array)
+
+Returns the structure that has been changed, as an array.
+
+When a resource was added or removed, the result is an empty array. That's because all of the parameters and other metadata from the resource exist entirely in one catalog but not the other.
+
+When a resource has changed, one diff is created for each parameter that changed. For example, both the old and new catalogs contain the file resource `/etc/foo` but just the content has changed:
+
+```
+# Old
+file { '/etc/foo':
+  owner   => 'root',
+  content => 'This is the old file',
+}
+
+# New
+file { '/etc/foo':
+  owner   => 'root',
+  content => 'This is the NEW FILE!!!!!',
+}
+```
+
+Internally, the Puppet catalog for this resource will look like this in the catalogs (this has been abbreviated a bit for clarity):
+
+```
+# Old
+{
+  "type": "File",
+  "title": "/etc/foo",
+  "exported": false,
+  "parameters": {
+    "owner": "root",
+    "content": "This is the old file"
+  }
+}
+
+# New
+{
+  "type": "File",
+  "title": "/etc/foo",
+  "exported": false,
+  "parameters": {
+    "owner": "root",
+    "content": "This is the NEW FILE!!!!!"
+  }
+}
+```
+
+One diff will be generated to represent the change to the content of the file (which in the catalog is nested in the 'parameters' hash). The diff will be structured as follows:
+
+```
+diff.type #=> 'File'
+diff.title #=> '/etc/foo'
+diff.structure #=> ['parameters', 'content']
+```
+
+#### `#title` (String)
+
+Returns the title of the resource from the Puppet catalog.
+
+For example, a diff involving `File['/etc/passwd']` would have:
+
+- `diff.title #=> '/etc/passwd'`
+- `diff.type #=> 'File`
+
+#### `#type` (String)
+
+Returns the type of the resource from the Puppet catalog.
+
+For example, a diff involving `File['/etc/passwd']` would have:
+
+- `diff.title #=> '/etc/passwd'`
+- `diff.type #=> 'File`
+
+Note that the type will be capitalized because Puppet capitalizes this in catalogs.

spec/octocatalog-diff/tests/api/v1/diff_spec.rb

@@ -101,12 +101,34 @@
   end
 
   describe '#type' do
+    it 'should return the type' do
+      testobj = described_class.new(chg_2)
+      expect(testobj.type).to eq('File')
+    end
   end
 
   describe '#title' do
+    it 'should return the title when there is no structure' do
+      testobj = described_class.new(add_2)
+      expect(testobj.title).to eq('/etc/foo')
+    end
+
+    it 'should return the title when there is structure' do
+      testobj = described_class.new(chg_2)
+      expect(testobj.title).to eq('/etc/foo')
+    end
   end
 
   describe '#structure' do
+    it 'should return an empty array for an addition' do
+      testobj = described_class.new(add_2)
+      expect(testobj.structure).to eq([])
+    end
+
+    it 'should return the proper array for a change' do
+      testobj = described_class.new(chg_2)
+      expect(testobj.structure).to eq(%w(parameters content))
+    end
   end
 
   describe '#old_value' do