[aa-eval] Enhance the comments to better describe the overview of why this pass exists.

[chandlerc]

Summary

This is based on feedback received when moving this comment from the source
file to a new header file.

[reames]

LGTM. IMHO, this didn't really need review.

[chandlerc]

In D17476#359095, @reames wrote:

LGTM. IMHO, this didn't really need review.

Sure, but mostly wanted to make sure I was at least incorporating the insight you wanted to capture here. I'm not terribly familiar with AA eval in general so, ya know, what do I know. ;]

Also, I'm bad at writing English.

llvm/trunk/include/llvm/Analysis/AliasAnalysisEvaluator.h

 //===- AliasAnalysisEvaluator.h - Alias Analysis Accuracy Evaluator -------===//
 //
 //                     The LLVM Compiler Infrastructure
 //
 // This file is distributed under the University of Illinois Open Source
 // License. See LICENSE.TXT for details.
 //
 //===----------------------------------------------------------------------===//
-//
-// This file implements a simple N^2 alias analysis accuracy evaluator.
-// Basically, for each function in the program, it simply queries to see how the
-// alias analysis implementation answers alias queries between each pair of
-// pointers in the function.
-//
-// This is inspired and adapted from code by: Naveen Neelakantam, Francesco
-// Spadini, and Wojciech Stryjewski.
-//
+/// \file
+///
+/// This file implements a simple N^2 alias analysis accuracy evaluator. The
+/// analysis result is a set of statistics of how many times the AA
+/// infrastructure provides each kind of alias result and mod/ref result when
+/// queried with all pairs of pointers in the function.
+///
+/// It can be used to evaluate a change in an alias analysis implementation,
+/// algorithm, or the AA pipeline infrastructure itself. It acts like a stable
+/// and easily tested consumer of all AA information exposed.
+///
+/// This is inspired and adapted from code by: Naveen Neelakantam, Francesco
+/// Spadini, and Wojciech Stryjewski.
+///
 //===----------------------------------------------------------------------===//
 
 #ifndef LLVM_ANALYSIS_ALIASANALYSISEVALUATOR_H
 #define LLVM_ANALYSIS_ALIASANALYSISEVALUATOR_H
 
 #include "llvm/IR/Function.h"
 #include "llvm/IR/PassManager.h"