Rename SecurityStyleExplanations and WebSecurityStyle fields

content/public/browser/security_style_explanations.h

 // Copyright 2015 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.
 
 #ifndef CONTENT_PUBLIC_BROWSER_SECURITY_STYLE_EXPLANATIONS_H_
 #define CONTENT_PUBLIC_BROWSER_SECURITY_STYLE_EXPLANATIONS_H_
 
 #include <vector>
 
 #include "content/common/content_export.h"
 #include "content/public/browser/security_style_explanation.h"
 #include "third_party/WebKit/public/platform/WebSecurityStyle.h"
 
 namespace content {
 
 // SecurityStyleExplanations contains information about why a particular
 // SecurityStyle was chosen for a page. This information includes the
 // mixed content status of the page and whether the page was loaded over
 // a cryptographically secure transport. Additionally,
 // SecurityStyleExplanations contains human-readable
 // SecurityStyleExplanation objects that the embedder can use to
 // describe embedder-specific security policies. Each
 // SecurityStyleExplanation is a single security property of a page (for
 // example, an expired certificate, a valid certificate, or the presence
 // of a deprecated crypto algorithm). A single site may have multiple
-// different explanations of "secure", "warning", "broken", and "info" severity
-// levels.
+// different explanations of "secure", "warning", "insecure", and "info"
+// severity levels.

[elawrence, 2017/03/22 19:43:07]

This comment remains a bit confusing, partly because we start by talking about a
"page" and end up talking about a "site." Fixing that word alone is probably
sufficient, but maybe we could provide a little more context? 
 
SecurityStyleExplanations provide context for why the specific SecurityStyle was
chosen for the page. 

Each page has a single SecurityStyle, which is chosen based on factors like
whether the page was delivered over HTTPS with a valid certificate, is free of
mixed-content, does not use a deprecated protocol, and is not flagged as
dangerous. 

Each factor that impacts the SecurityStyle has an accompanying
SecurityStyleExplanation that contains a human-readable explanation of the
factor. A single page may contain multiple explanations, each of which may have
a different severity level ("secure", "warning", "insecure" and "info").


---
I think part of the reason that this is so wordy is that it's written to be
generic (despite the primary use within the Developer Tools). But we probably
can just say "secure protocol" instead of "cryptographically secure transport",
etc.

[estark, 2017/03/22 20:41:29]

Done, thanks for the suggested wording.

 struct SecurityStyleExplanations {
   CONTENT_EXPORT SecurityStyleExplanations();
   CONTENT_EXPORT SecurityStyleExplanations(
       const SecurityStyleExplanations& other);
   CONTENT_EXPORT ~SecurityStyleExplanations();
 
   // True if the page was loaded over HTTPS and ran mixed (HTTP) content
   // such as scripts.
   bool ran_mixed_content;
   // True if the page was loaded over HTTPS and displayed mixed (HTTP)
@@ skipping 24 matching lines @@
 
   bool scheme_is_cryptographic;
 
   // True if PKP was bypassed due to a local trust anchor.
   bool pkp_bypassed;
 
   // User-visible summary of the security style, set only when
   // the style cannot be determined from HTTPS status alone.
   std::string summary;
 
-  // Explanations corresponding to each security level. The embedder should
-  // display explanations in the order: broken, unauthenticated, secure, info.
+  // Explanations corresponding to each security level.
+
+  // |secure_explanations| explains why the page was marked secure.
   std::vector<SecurityStyleExplanation> secure_explanations;
-  std::vector<SecurityStyleExplanation> unauthenticated_explanations;
-  std::vector<SecurityStyleExplanation> broken_explanations;
+  // |neutral_explanations| explains why the page was marked neutrally: for
+  // example, the page's lock icon was taken away due to mixed content, or the
+  // page was not loaded over HTTPS.
+  std::vector<SecurityStyleExplanation> neutral_explanations;
+  // |insecure_explanations| explains why the page was marked as insecure or
+  // dangerous: for example, the page was loaded with a certificate error.
+  std::vector<SecurityStyleExplanation> insecure_explanations;
+  // |info_explanations| contains information that did not affect the page's
+  // security style, but is still relevant to the page's security state: for
+  // example, an upcoming deprecation that will affect the security style in
+  // future.
   std::vector<SecurityStyleExplanation> info_explanations;
 };
 
 }  // namespace content
 
 #endif  // CONTENT_PUBLIC_BROWSER_SECURITY_STYLE_EXPLANATION_H_