glide.yaml: update inline comments

glide.yaml

-# NOTE(ericchiang): Create a separate block for each dependency so it's clear
-# which dependencies require which transitive dependencies.
+# For detailed docs on how to add new dependencies or
+# update dependencies see Documentation/dev-dependencies.md
+#
+# The TL;DR is:
+# * Use glide and glide-vc.
+# * List transitive dependencies.
+# * Create a separate block for each dependency group.
+# * Keep updates to "vendor/" in a seperate commit from actual changes.
 
 package: github.com/coreos/dex
 import:
@@ -11,17 +17,20 @@ import:
 - package: github.com/inconshreveable/mousetrap
   version: 76626ae9c91c4f2a10f34cad8ce83ea42c93bb75
 
+# LDAP dependencies.
 - package: gopkg.in/ldap.v2
   version: 0e7db8eb77695b5a952f0e5d78df9ab160050c73
 - package: gopkg.in/asn1-ber.v1
   version: 4e86f4367175e39f69d9358a5f17b4dda270378d
 
+# Used for JOSE functionality (JWKs, JWTs, etc.).
 - package: gopkg.in/square/go-jose.v2
   version: v2.0.0
   subpackages:
   - cipher
   - json
 
+# Imported directly and by several third party packages.
 - package: golang.org/x/net
   version: 6a513affb38dc9788b449d59ffed099b8de18fa0
   subpackages:
@@ -33,16 +42,21 @@ import:
   - lex/httplex
   - trace
 
+# Used for parsing configs.
 - package: github.com/ghodss/yaml
   version: bea76d6a4713e18b7f5321a2b020738552def3ea
 - package: gopkg.in/yaml.v2
   version: a83829b6f1293c91addabc89d0571c246397bbf4
 
+# Router used by the server.
 - package: github.com/gorilla/mux
   version: 9fa818a44c2bf1396a17f9d5a3c0f6dd39d2ff8e
 - package: github.com/gorilla/context
   version: aed02d124ae4a0e94fea4541c8effd05bf0c8296
 
+# Package with a bunch of sane crypto defaults. Consider just
+# copy the code (as recommended by the repo itself) instead
+# of importing.
 - package: github.com/gtank/cryptopasta
   version: e7e23673cac3f529f49e22f94e4af6d12bb49dba
 - package: golang.org/x/crypto
@@ -50,6 +64,7 @@ import:
   subpackages:
   - bcrypt
 
+# Used for server integration tests and OpenID Connect connector.
 - package: github.com/coreos/go-oidc
   version: dedb650fb29c39c2f21aa88c1e4cec66da8754d1
 - package: github.com/pquerna/cachecontrol
@@ -71,13 +86,8 @@ import:
   - internal/datastore
   - internal/log
   - internal/remote_api
-# Go's protobuf generator is also a direct dependency of this repo.
-- package: github.com/golang/protobuf
-  version: 874264fbbb43f4d91e999fecb4b40143ed611400
-  subpackages:
-  - proto
-  - protoc-gen-go
 
+# Testing conveniences.
 - package: github.com/kylelemons/godebug
   subpackages:
   - diff
@@ -96,7 +106,7 @@ import:
   subpackages:
   - crdb
 
-# gRPC also imports protobuf and the x/net/http2 stack.
+# gRPC and protobuf are use for the API. Also import x/net/http2 stack.
 - package: google.golang.org/grpc
   version: b1a2821ca5a4fd6b6e48ddfbb7d6d7584d839d21
   subpackages:
@@ -108,3 +118,8 @@ import:
   - naming
   - peer
   - transport
+- package: github.com/golang/protobuf
+  version: 874264fbbb43f4d91e999fecb4b40143ed611400
+  subpackages:
+  - proto
+  - protoc-gen-go