Update some documentation for CertVerifyResult::verified_cert

net/cert/cert_verify_proc.h

 // Copyright (c) 2012 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 NET_CERT_CERT_VERIFY_PROC_H_
 #define NET_CERT_CERT_VERIFY_PROC_H_
 
 #include <string>
 #include <vector>
 
@@ skipping 73 matching lines @@
  private:
   friend class base::RefCountedThreadSafe<CertVerifyProc>;
   FRIEND_TEST_ALL_PREFIXES(CertVerifyProcTest, DigiNotarCerts);
   FRIEND_TEST_ALL_PREFIXES(CertVerifyProcTest, TestHasTooLongValidity);
   FRIEND_TEST_ALL_PREFIXES(CertVerifyProcTest,
                            VerifyRejectsSHA1AfterDeprecationLegacyMode);
 
   // Performs the actual verification using the desired underlying
   // cryptographic library. On entry, |verify_result->verified_cert|
   // is set to |cert|, the unverified chain. If no chain is built, the
-  // value must be left untouched.
+  // value must be left untouched. On entry, |verify_result| is in a
+  // default-initialized state.
+  //
+  // Implementations of VerifyInternal() are responsible for filling in all
+  // applicable fields of |verify_result| EXCEPT for |ocsp_result|, which
+  // will be filled in by Verify().

[Ryan Sleevi, 2017/01/09 23:20:14]

Note quite true here: 

|verify_result| is explicitly initialized to set |verified_cert|

The contract might be better specified:

On entry, |verify_result| will be default-initialized as a successful
validation, with |verify_result->verified_cert| set to |cert|. Implementations
are expected to fill in all applicable fields, excluding |ocsp_result|, which
will be filled in by |Verify()|.  If an error code is returned,
|verify_result->cert_status| should be non-zero, indicating an error occurred.
On success, net::OK should be returned, with |verify_result| updated to reflect
the successfully verified chain.

IDK, WDYT?

[eroman, 2017/01/09 23:33:12]

Done.

   virtual int VerifyInternal(X509Certificate* cert,
                              const std::string& hostname,
                              const std::string& ocsp_response,
                              int flags,
                              CRLSet* crl_set,
                              const CertificateList& additional_trust_anchors,
                              CertVerifyResult* verify_result) = 0;
 
   // Returns true if |cert| is explicitly blacklisted.
   static bool IsBlacklisted(X509Certificate* cert);
@@ skipping 41 matching lines @@
 // This function is intended to be used as a helper by platform-specific
 // CertVerifyProc implementations.
 X509Certificate::SignatureHashAlgorithm FillCertVerifyResultWeakSignature(
     X509Certificate::OSCertHandle cert,
     bool is_leaf,
     CertVerifyResult* verify_result);
 
 }  // namespace net
 
 #endif  // NET_CERT_CERT_VERIFY_PROC_H_