diff --git a/llvm/include/llvm/Support/Error.h b/llvm/include/llvm/Support/Error.h
--- a/llvm/include/llvm/Support/Error.h
+++ b/llvm/include/llvm/Support/Error.h
@@ -436,6 +436,49 @@
 /// Error cannot be copied, this class replaces getError() with
 /// takeError(). It also adds an bool errorIsA<ErrT>() method for testing the
 /// error class type.
+///
+/// Example usage of 'Expected<T>' as a return type:
+///
+///   @code{.cpp}
+///     Expected<int> myDivide(int A, int B) {
+///       if (B == 0) {
+///         // return an Error
+///         return error("B must not be zero!");
+///       }
+///       // return an integer
+///       return A / B;
+///     }
+///   @endcode
+///
+///   Checking the results of to a function returning 'Expected<T>':
+///   @code{.cpp}
+///     auto Result = myDivide(X,Y);
+///     if (!Result) {
+///       auto Error = Result.takeError();
+///       // handle the error case here
+///     } else {
+///       // handle good case here
+///     }
+///
+///   @endcode
+///
+///  Unit-testing a function returning an 'Expceted<T>':
+///   @code{.cpp}
+///   TEST(MyTests, ExpectedDemo) {
+///     auto Passed = myDivide(10, 5);
+///     // check this call has passed, this also prints the error message
+///     // if the function returns an Error
+///     ASSERT_TRUE((bool)Passed) << llvm::toString(Passed.takeError());
+///     // checked the returned value
+///     ASSERT_EQ(2, *Passed);
+///
+///     auto Failed = myDivide(1, 0);
+///     ASSERT_FALSE((bool)Failed);
+///     // make sure Failed.takeError() does not get remove by the optimizer
+///     std::cout << "Expected failure: " << llvm::toString(Failed.takeError());
+///   }
+///   @endcode
+
 template <class T> class LLVM_NODISCARD Expected {
   template <class T1> friend class ExpectedAsOutParameter;
   template <class OtherT> friend class Expected;