From 84828075d0d711460567d521b07a30fd664979d5 Mon Sep 17 00:00:00 2001
From: Matt Silverlock <matt@eatsleeprepeat.net>
Date: Thu, 6 Aug 2015 15:24:19 +0800
Subject: Improved documentation for CodecsFromPairs.

- Partially addresses https://github.com/gorilla/sessions/issues/48
- Downstream store packages will need to perform the type assertion in their code
- Elected to document this and fix stores rather than add a function to the
  public API.
---
 securecookie.go | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/securecookie.go b/securecookie.go
index 7c05972..7dd373d 100644
--- a/securecookie.go
+++ b/securecookie.go
@@ -484,7 +484,29 @@ func GenerateRandomKey(length int) []byte {
 
 // CodecsFromPairs returns a slice of SecureCookie instances.
 //
-// It is a convenience function to create a list of codecs for key rotation.
+// It is a convenience function to create a list of codecs for key rotation. Note
+// that the generated Codecs will have the default options applied: callers
+// should iterate over each Codec and type-assert the underlying *SecureCookie to
+// change these.
+//
+// Example:
+//
+//      codecs := securecookie.CodecsFromPairs(
+//           []byte("new-hash-key"),
+//           []byte("new-block-key"),
+//           []byte("old-hash-key"),
+//           []byte("old-block-key"),
+//       )
+//
+//      // Modify each instance.
+//      for _, s := range codecs {
+//             if cookie, ok := s.(*securecookie.SecureCookie); ok {
+//                 cookie.MaxAge(86400 * 7)
+//                 cookie.SetSerializer(securecookie.JSONEncoder{})
+//                 cookie.HashFunc(sha512.New512_256)
+//             }
+//         }
+//
 func CodecsFromPairs(keyPairs ...[]byte) []Codec {
 	codecs := make([]Codec, len(keyPairs)/2+len(keyPairs)%2)
 	for i := 0; i < len(keyPairs); i += 2 {
-- 
cgit v1.2.3