Improve documentation of CertVerifier::Verify() regarding |out_req|.

net/cert/cert_verifier.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_VERIFIER_H_
 #define NET_CERT_CERT_VERIFIER_H_
 
 #include <string>
 
 #include "base/basictypes.h"
 #include "net/base/completion_callback.h"
 #include "net/base/net_export.h"
 
 namespace net {
 
 class BoundNetLog;
 class CertVerifyResult;
 class CRLSet;
 class X509Certificate;
 
 // CertVerifier represents a service for verifying certificates.
 //
 // CertVerifiers can handle multiple requests at a time.
 class NET_EXPORT CertVerifier {
  public:
   class Request {
    public:
+    Request() {}
+
     // Destruction of the Request cancels it.
     virtual ~Request() {}
+
+   private:
+    DISALLOW_COPY_AND_ASSIGN(Request);
   };
 
   enum VerifyFlags {
     // If set, enables online revocation checking via CRLs and OCSP for the
     // certificate chain.
     VERIFY_REV_CHECKING_ENABLED = 1 << 0,
 
     // If set, and the certificate being verified may be an EV certificate,
     // attempt to verify the certificate according to the EV processing
     // guidelines. In order to successfully verify a certificate as EV,
@@ skipping 52 matching lines @@
   // VERIFY_REV_CHECKING_ENABLED is not set), EV certificate verification will
   // not be performed.
   //
   // |crl_set| points to an optional CRLSet structure which can be used to
   // avoid revocation checks over the network.
   //
   // |callback| must not be null.  ERR_IO_PENDING is returned if the operation
   // could not be completed synchronously, in which case the result code will
   // be passed to the callback when available.
   //
-  // |*out_req| will be filled with a pointer to the asynchronous request.
-  // Freeing this pointer before the request has completed will cancel it.
+  // On asynchronous completion (when Verify returns ERR_IO_PENDING) |out_req|
+  // will be reset with a pointer to the request. Freeing this pointer before
+  // the request has completed will cancel it.
+  //
+  // If Verify() completes synchronously then |out_req| *may* be reset to
+  // nullptr. However it is not guaranteed that all implementations will reset
+  // it in this case.
   //
   // TODO(rsleevi): Move CRLSet* out of the CertVerifier signature.
   virtual int Verify(X509Certificate* cert,
                      const std::string& hostname,
                      const std::string& ocsp_response,
                      int flags,
                      CRLSet* crl_set,
                      CertVerifyResult* verify_result,
                      const CompletionCallback& callback,
                      scoped_ptr<Request>* out_req,
                      const BoundNetLog& net_log) = 0;
 
   // Returns true if this CertVerifier supports stapled OCSP responses.
   virtual bool SupportsOCSPStapling();
 
   // Creates a CertVerifier implementation that verifies certificates using
   // the preferred underlying cryptographic libraries.
   static CertVerifier* CreateDefault();
 };
 
 }  // namespace net
 
 #endif  // NET_CERT_CERT_VERIFIER_H_