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,39 @@
 /// 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 function return type:
+///
+///   @code{.cpp}
+///     Expected<int> myDivide(int A, int B) {
+///       if (B == 0) {
+///         // return an Error
+///         return createStringError(inconvertibleErrorCode(),
+///                                  "B must not be zero!");
+///       }
+///       // return an integer
+///       return A / B;
+///     }
+///   @endcode
+///
+///   Checking the results of to a function returning 'Expected<T>':
+///   @code{.cpp}
+///     if (auto E = Result.takeError()) {
+///       // We must consume the error. Typically one of:
+///       // - return the error to our caller
+///       // - toString(), when logging
+///       // - consumeError(), to silently swallow the error
+///       // - handleErrors(), to distinguish error types
+///       errs() << "Problem with division " << toString(std::move(E)) << "\n";
+///       return;
+///     }
+///     // use the result
+///     outs() << "The answer is " << *Result << "\n";
+///   @endcode
+///
+///  For unit-testing a function returning an 'Expceted<T>', see the
+///  'EXPECT_THAT_EXPECTED' macros in llvm/Testing/Support/Error.h
+
 template <class T> class LLVM_NODISCARD Expected {
   template <class T1> friend class ExpectedAsOutParameter;
   template <class OtherT> friend class Expected;
diff --git a/llvm/include/llvm/Testing/Support/Error.h b/llvm/include/llvm/Testing/Support/Error.h
--- a/llvm/include/llvm/Testing/Support/Error.h
+++ b/llvm/include/llvm/Testing/Support/Error.h
@@ -165,6 +165,27 @@
 #define ASSERT_THAT_ERROR(Err, Matcher)                                        \
   ASSERT_THAT(llvm::detail::TakeError(Err), Matcher)
 
+/// Helper macro for checking the result of an 'Expected<T>'
+///
+///   @code{.cpp}
+///     // function to be tested
+///     Expected<int> myDivide(int A, int B);
+///
+///     TEST(myDivideTests, GoodAndBad) {
+///       // test good case
+///       // if you only care about success or failure:
+///       EXPECT_THAT_EXPECTED(myDivide(10, 5), Succeeded());
+///       // if you also care about the value:
+///       EXPECT_THAT_EXPECTED(myDivide(10, 5), HasValue(2));
+///
+///       // test the error case
+///       EXPECT_THAT_EXPECTED(myDivide(10, 0), Failed());
+///       // also check the error message
+///       EXPECT_THAT_EXPECTED(myDivide(10, 0),
+///           FailedWithMessage("B must not be zero!"));
+///     }
+///   @endcode
+
 #define EXPECT_THAT_EXPECTED(Err, Matcher)                                     \
   EXPECT_THAT(llvm::detail::TakeExpected(Err), Matcher)
 #define ASSERT_THAT_EXPECTED(Err, Matcher)                                     \