Add example of throws(E) vs rethrows

Author: amartini51

TSPL.docc/ReferenceManual/Declarations.md

@@ -1594,18 +1594,26 @@ and a throwing method can't satisfy a protocol requirement for a rethrowing meth
 That said, a rethrowing method can override a throwing method,
 and a rethrowing method can satisfy a protocol requirement for a throwing method.
 
-<!-- XXX comparison between rethrows and generic typed throws 
+An alternative to rethrowing is throwing a specific error type in generic code.
+For example:
 
-func f<E: Error>(closure: () throws(E) -> Int) throws(E) -> Int { ... }
-func g(closure: () throws -> Int) rethrows -> Int { ... }
+```swift
+func someFunction<E: Error>(callback: () throws(E) -> Void) throws(E) {
+    try callback()
+}
+```
 
-map() from the stdlib is another example
+This approach to propagating an error
+preserves type information about the error.
+However, unlike marking a function `rethrows`,
+this approach doesn't prevent the function
+from throwing an error of the same type.
 
-XXX FROM DOUG
-Part of me wants to suggest that this whole section be revised to replace rethrows entirely with the use of generic typed throws, because that's how I expect the language to go over time. Then, rethrows would become more of a historical anecdote. However, that is a lot of work, and perhaps we'll find that rethrows will remain for longer than I expect. If so, I think it's fine to keep this comparison short: take the someFunction example from the beginning of the section and make it generic over the thrown error type, and note that it's providing a more precise guarantee about what errors it rethrows than rethrows does (because rethrows always produces an any Error).
-XXX END FROM DOUG
+<!--
+TODO: Revisit the comparison between rethrows and throws(E) above,
+since it seems likely that the latter will generally replace the former.
 
-Filed rdar://128972373
+See also rdar://128972373
 -->
 
 ### Asynchronous Functions and Methods