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,40 @@
 /// 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}
+///     auto Result = myDivide(X,Y);
+///     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(E) << "\n";
+///     }
+///     // 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,29 @@
 #define ASSERT_THAT_ERROR(Err, Matcher)                                        \
   ASSERT_THAT(llvm::detail::TakeError(Err), Matcher)
 
+/// Helper marcro 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 the good care
+///       auto D1 = myDivide(10, 5);
+///       // ensure the Error gets consumed in case the function fails by
+///       // calling 'toString()'. This also helps in debugging failing tests.
+///       EXPECT_THAT_EXPECTED(D1, Succeeded()) << toString(D1.takeError()) <<
+///         "\n";
+///       EXPECT_THAT(*D1, Eq(2));
+///
+///       // test the error case
+///       auto D2 = myDivide(10, 0);
+///       EXPECT_THAT_EXPECTED(D2, Failed());
+///       // In the error case we need to consume the error.
+///       consumeError(D2.takeError());
+///     }
+///   @endcode
+
 #define EXPECT_THAT_EXPECTED(Err, Matcher)                                     \
   EXPECT_THAT(llvm::detail::TakeExpected(Err), Matcher)
 #define ASSERT_THAT_EXPECTED(Err, Matcher)                                     \