Add more documentation for GN header checking

tools/gn/header_checker.cc

 // Copyright 2014 The Chromium Authors. All rights reserved.
 // Use of this source code is governed by a BSD-style license that can be
 // found in the LICENSE file.
 
 #include "tools/gn/header_checker.h"
 
 #include <algorithm>
 
 #include "base/bind.h"
 #include "base/files/file_util.h"
@@ skipping 280 matching lines @@
   while (iter.GetNextIncludeString(&current_include, &range)) {
     SourceFile include = SourceFileForInclude(current_include);
     if (!CheckInclude(from_target, input_file, include, range, err))
       return false;
   }
 
   return true;
 }
 
 // If the file exists:
-//  - It must be in one or more dependencies of the given target.
-//  - Those dependencies must have visibility from the source file.
-//  - The header must be in the public section of those dependeices.
-//  - Those dependencies must either have no direct dependent configs with
-//    flags that affect the compiler, or those direct dependent configs apply
-//    to the "from_target" (it's one "hop" away). This ensures that if the
-//    include file needs needs compiler settings to compile it, that those
-//    settings are applied to the file including it.
+//  - The header must be in the public section of a target, or it must
+//    be in the sources with no public list (everything is implicitly public).
+//  - The dependency path to the included target must follow only public_deps.
+//  - If there are multiple targets with the header in it, only one need be
+//    valid for the check to pass.
 bool HeaderChecker::CheckInclude(const Target* from_target,
                                  const InputFile& source_file,
                                  const SourceFile& include_file,
                                  const LocationRange& range,
                                  Err* err) const {
   // Assume if the file isn't declared in our sources that we don't need to
   // check it. It would be nice if we could give an error if this happens, but
   // our include finder is too primitive and returns all includes, even if
   // they're in a #if not executed in the current build. In that case, it's
   // not unusual for the buildfiles to not specify that header at all.
@@ skipping 258 matching lines @@
   if (targets_with_other_toolchains.size() +
       targets_with_matching_toolchains.size() > 1)
     msg += "at least one of ";
   msg += "which should somehow be reachable.";
 
   // Danger: must call CreatePersistentRange to put in Err.
   return Err(CreatePersistentRange(source_file, range),
              "Include not allowed.", msg);
 }