Utilities improvements and docs

Source/Utilities.swift

@@ -8,18 +8,21 @@
 import Metal
 import Upsurge
 
+/// Convert a Metal buffer to an `UnsafeMutableBufferPointer`
 public func unsafeBufferPointerFromBuffer(buffer: MTLBuffer) -> UnsafeMutableBufferPointer<Float> {
     let pointer = UnsafeMutablePointer<Float>(buffer.contents())
     let count = buffer.length / sizeof(Float)
     return UnsafeMutableBufferPointer(start: pointer, count: count)
 }
 
-public func arrayFromBuffer(buffer: MTLBuffer, start: Int = 0) -> Array<Float> {
+/// Copy the contents of a Metal buffer to an array
+public func arrayFromBuffer(buffer: MTLBuffer, start: Int = 0, count: Int? = nil) -> Array<Float> {
     let pointer = UnsafePointer<Float>(buffer.contents()) + start
-    let count = buffer.length / sizeof(Float) - start
+    let count = count ?? buffer.length / sizeof(Float) - start
     return Array<Float>(UnsafeBufferPointer(start: pointer, count: count))
 }
 
+/// Copy the contents of a Metal buffer to a ValueArray
 public func valueArrayFromBuffer(buffer: MTLBuffer, start: Int = 0, count: Int? = nil) -> ValueArray<Float> {
     let pointer = UnsafeMutablePointer<Float>(buffer.contents()) + start
     let count = count ?? buffer.length / sizeof(Float) - start
@@ -28,6 +31,7 @@ public func valueArrayFromBuffer(buffer: MTLBuffer, start: Int = 0, count: Int?
     return array
 }
 
+/// Copy a collection of values to a Metal buffer
 public func fillBuffer<Collection: CollectionType where Collection.Generator.Element == Float>(buffer: MTLBuffer, start: Int, withElements elements: Collection) {
     let pointer = UnsafeMutablePointer<Float>(buffer.contents()) + start
     for (i, v) in elements.enumerate() {