Index: lib/Format/ContinuationIndenter.h
===================================================================
--- lib/Format/ContinuationIndenter.h
+++ lib/Format/ContinuationIndenter.h
@@ -32,6 +32,8 @@
 struct ParenState;
 class WhitespaceManager;
 
+/// \brief Helper class for breaking a logical line into multiple physical
+/// lines.  Manages moving state from one physical line to the next.
 class ContinuationIndenter {
 public:
   /// \brief Constructs a \c ContinuationIndenter to format \p Line starting in
Index: lib/Format/Format.cpp
===================================================================
--- lib/Format/Format.cpp
+++ lib/Format/Format.cpp
@@ -758,6 +758,7 @@
 
 namespace {
 
+/// \brief Responsible for splitting up a file into \c FormatTokens.
 class FormatTokenLexer {
 public:
   FormatTokenLexer(SourceManager &SourceMgr, FileID ID, FormatStyle &Style,
@@ -1417,6 +1418,15 @@
   }
 }
 
+/// \brief Responsible for taking a file and producing whitespace adjustments
+/// to reformat the file according to a desired style.
+///
+/// The pipeline used by \c Formatter:
+/// -# A \c FormatTokenLexer splits the file into raw tokens
+/// -# A \c UnwrappedLineParser converts those into logical lines
+/// -# A \c TokenAnnotator computes metadata for the tokens in each line
+/// -# A \c UnwrappedLineFormatter then produces whitespace adjustments
+///    which result in the desired logical lines
 class Formatter : public UnwrappedLineConsumer {
 public:
   Formatter(const FormatStyle &Style, SourceManager &SourceMgr, FileID ID,
Index: lib/Format/FormatToken.h
===================================================================
--- lib/Format/FormatToken.h
+++ lib/Format/FormatToken.h
@@ -107,8 +107,8 @@
 class TokenRole;
 class AnnotatedLine;
 
-/// \brief A wrapper around a \c Token storing information about the
-/// whitespace characters preceding it.
+/// \brief A wrapper around a \c Token storing additional information useful
+/// for formatting.
 struct FormatToken {
   FormatToken() {}
 
Index: lib/Format/TokenAnnotator.h
===================================================================
--- lib/Format/TokenAnnotator.h
+++ lib/Format/TokenAnnotator.h
@@ -36,6 +36,7 @@
   LT_VirtualFunctionDecl
 };
 
+/// \brief Stores additional information for an \c UnwrappedLine.
 class AnnotatedLine {
 public:
   AnnotatedLine(const UnwrappedLine &Line)
@@ -148,7 +149,11 @@
   // FIXME: Can/should this be done in the UnwrappedLineParser?
   void setCommentLineLevels(SmallVectorImpl<AnnotatedLine *> &Lines);
 
+  /// \brief Compute metadata of \c AnnotatedLine itself, like \c LineType.
   void annotate(AnnotatedLine &Line);
+
+  /// \brief For all the tokens in \c Line, compute if a line break is
+  /// needed for that token, and similar information.
   void calculateFormattingInformation(AnnotatedLine &Line);
 
 private:
Index: lib/Format/UnwrappedLineFormatter.h
===================================================================
--- lib/Format/UnwrappedLineFormatter.h
+++ lib/Format/UnwrappedLineFormatter.h
@@ -28,6 +28,9 @@
 class ContinuationIndenter;
 class WhitespaceManager;
 
+/// \brief Responsible for taking a list of logical lines, and for producing
+/// a set of whitespace adjustments to turn them into physical lines so
+/// that each physical line is below a column limit.
 class UnwrappedLineFormatter {
 public:
   UnwrappedLineFormatter(ContinuationIndenter *Indenter,
Index: lib/Format/UnwrappedLineParser.h
===================================================================
--- lib/Format/UnwrappedLineParser.h
+++ lib/Format/UnwrappedLineParser.h
@@ -58,6 +58,8 @@
 
 class FormatTokenSource;
 
+/// \brief Takes a sequence of tokens, and splits it into chunks of tokens
+/// that would be a single line each if there was no column limit.
 class UnwrappedLineParser {
 public:
   UnwrappedLineParser(const FormatStyle &Style,