Merge pull request #152 from onflow/bastian/151-fix-capablities-type-…

…definition

Update account capabilities type definitions

docs/language/accounts/capabilities.mdx

@@ -23,14 +23,15 @@ struct Capabilities {
     let account: Account.AccountCapabilities
 
     /// Returns the capability at the given public path.
-    /// Returns nil if the capability does not exist,
-    /// or if the given type is not a supertype of the capability's borrow type.
+    /// If the capability does not exist,
+    /// or if the given type is not a supertype of the capability's borrow type,
+    /// returns an "invalid" capability with ID 0 that will always fail to `check` or `borrow`
     access(all)
-    view fun get<T: &Any>(_ path: PublicPath): Capability<T>?
+    view fun get<T: &Any>(_ path: PublicPath): Capability<T>
 
     /// Borrows the capability at the given public path.
     /// Returns nil if the capability does not exist, or cannot be borrowed using the given type.
-    /// The function is equivalent to `get(path)?.borrow()`.
+    /// The function is equivalent to `get(path).borrow()`.
     access(all)
     view fun borrow<T: &Any>(_ path: PublicPath): T?
 
@@ -80,15 +81,15 @@ that was [published](#publishing-capabilities) before.
 
 ```cadence
 access(all)
-view fun get<T: &Any>(_ path: PublicPath): Capability<T>?
+view fun get<T: &Any>(_ path: PublicPath): Capability<T>
 ```
 
 If the account has a capability with the given type published under the given path,
-the function returns it as an optional.
+the function returns it.
 
 If the account has no capability published under the given path,
-or the requested type, via the type parameter `T`, does not match the published capability,
-the function returns `nil`.
+or if the given type is not a supertype of the capability's borrow type,
+the function returns an "invalid" capability with ID 0 that will always fail to `check` or `borrow`.
 
 The convenience function `capabilities.borrow` obtains and borrows a public capability
 that was [published](#publishing-capabilities) before, in one step.
@@ -136,6 +137,10 @@ struct StorageCapabilities {
     access(Capabilities | StorageCapabilities | IssueStorageCapabilityController)
     fun issue<T: &Any>(_ path: StoragePath): Capability<T>
 
+    /// Issue/create a new storage capability.
+    access(Capabilities | StorageCapabilities | IssueStorageCapabilityController)
+    fun issueWithType(_ path: StoragePath, type: Type): Capability
+
     /// Get the storage capability controller for the capability with the specified ID.
     ///
     /// Returns nil if the ID does not reference an existing storage capability.
@@ -170,6 +175,10 @@ struct AccountCapabilities {
     access(Capabilities | AccountCapabilities | IssueAccountCapabilityController)
     fun issue<T: &Account>(): Capability<T>
 
+    /// Issue/create a new account capability.
+    access(Capabilities | AccountCapabilities | IssueAccountCapabilityController)
+    fun issueWithType(_ type: Type): Capability
+
     /// Get capability controller for capability with the specified ID.
     ///
     /// Returns nil if the ID does not reference an existing account capability.