Merge pull request #71 from liggitt/godoc-gofmt

Update godoc, add gofmt check

.githooks/pre-push

@@ -0,0 +1,6 @@
+#!/usr/bin/env bash
+
+# install from the root of the repo with:
+#   ln -s ../../.githooks/pre-push .git/hooks/pre-push
+
+make vet fmt lint

.travis.yml

@@ -1,15 +1,24 @@
 language: go
+env:
+    global:
+        - VET_VERSIONS="1.5 1.6 tip"
+        - LINT_VERSIONS="1.5 1.6 tip"
 go:
     - 1.2
     - 1.3
     - 1.4
     - 1.5
+    - 1.6
     - tip
 go_import_path: gopkg.in/ldap.v2
 install:
     - go get gopkg.in/asn1-ber.v1
     - go get gopkg.in/ldap.v2
     - go get code.google.com/p/go.tools/cmd/cover || go get golang.org/x/tools/cmd/cover
+    - go get github.com/golang/lint/golint || true
     - go build -v ./...
 script:
-    - go test -v -cover ./... 
+    - make test
+    - make fmt
+    - if [[ "$VET_VERSIONS"  == *"$TRAVIS_GO_VERSION"* ]]; then make vet; fi
+    - if [[ "$LINT_VERSIONS" == *"$TRAVIS_GO_VERSION"* ]]; then make lint; fi

Makefile

@@ -0,0 +1,42 @@
+.PHONY: default install build test quicktest fmt vet lint 
+
+default: fmt vet lint build quicktest
+
+install:
+	go get -t -v ./...
+
+build:
+	go build -v ./...
+
+test:
+	go test -v -cover ./...
+
+quicktest:
+	go test ./...
+
+# Capture output and force failure when there is non-empty output
+fmt:
+	@echo gofmt -l .
+	@OUTPUT=`gofmt -l . 2>&1`; \
+	if [ "$$OUTPUT" ]; then \
+		echo "gofmt must be run on the following files:"; \
+		echo "$$OUTPUT"; \
+		exit 1; \
+	fi
+
+# Only run on go1.5+
+vet:
+	go tool vet -atomic -bool -copylocks -nilfunc -printf -shadow -rangeloops -unreachable -unsafeptr -unusedresult .
+
+# https://github.com/golang/lint
+# go get github.com/golang/lint/golint
+# Capture output and force failure when there is non-empty output
+# Only run on go1.5+
+lint:
+	@echo golint ./...
+	@OUTPUT=`golint ./... 2>&1`; \
+	if [ "$$OUTPUT" ]; then \
+		echo "golint errors:"; \
+		echo "$$OUTPUT"; \
+		exit 1; \
+	fi

README.md

@@ -13,41 +13,39 @@ Import the latest version with:
 
     import "gopkg.in/ldap.v2"
 
-
 ## Required Libraries:
 
  - gopkg.in/asn1-ber.v1
 
-## Working:
+## Features:
 
- - Connecting to LDAP server
+ - Connecting to LDAP server (non-TLS, TLS, STARTTLS)
  - Binding to LDAP server
  - Searching for entries
- - Compiling string filters to LDAP filters
+ - Filter Compile / Decompile
  - Paging Search Results
  - Modify Requests / Responses
  - Add Requests / Responses
  - Delete Requests / Responses
- - Better Unicode support
 
 ## Examples:
 
  - search
  - modify
 
-## Tests Implemented:
-
- - Filter Compile / Decompile
-
-## TODO:
+## Contributing:
 
- - [x] Add Requests / Responses
- - [x] Delete Requests / Responses
- - [x] Modify DN Requests / Responses
- - [ ] Compare Requests / Responses
- - [ ] Implement Tests / Benchmarks
+Bug reports and pull requests are welcome!
 
+Before submitting a pull request, please make sure tests and verification scripts pass:
+```
+make all
+```
 
+To set up a pre-push hook to run the tests and verify scripts before pushing:
+```
+ln -s ../../.githooks/pre-push .git/hooks/pre-push
+```
 
 ---
 The Go gopher was designed by Renee French. (http://reneefrench.blogspot.com/)

add.go

@@ -16,8 +16,11 @@ import (
 	"gopkg.in/asn1-ber.v1"
 )
 
+// Attribute represents an LDAP attribute
 type Attribute struct {
+	// Type is the name of the LDAP attribute
 	Type string
+	// Vals are the LDAP attribute values
 	Vals []string
 }
 
@@ -32,8 +35,11 @@ func (a *Attribute) encode() *ber.Packet {
 	return seq
 }
 
+// AddRequest represents an LDAP AddRequest operation
 type AddRequest struct {
-	DN         string
+	// DN identifies the entry being added
+	DN string
+	// Attributes list the attributes of the new entry
 	Attributes []Attribute
 }
 
@@ -48,17 +54,20 @@ func (a AddRequest) encode() *ber.Packet {
 	return request
 }
 
+// Attribute adds an attribute with the given type and values
 func (a *AddRequest) Attribute(attrType string, attrVals []string) {
 	a.Attributes = append(a.Attributes, Attribute{Type: attrType, Vals: attrVals})
 }
 
+// NewAddRequest returns an AddRequest for the given DN, with no attributes
 func NewAddRequest(dn string) *AddRequest {
 	return &AddRequest{
 		DN: dn,
 	}
 
 }
 
+// Add performs the given AddRequest
 func (l *Conn) Add(addRequest *AddRequest) error {
 	packet := ber.Encode(ber.ClassUniversal, ber.TypeConstructed, ber.TagSequence, nil, "LDAP Request")
 	packet.AppendChild(ber.NewInteger(ber.ClassUniversal, ber.TypePrimitive, ber.TagInteger, l.nextMessageID(), "MessageID"))

bind.go

@@ -10,16 +10,22 @@ import (
 	"gopkg.in/asn1-ber.v1"
 )
 
+// SimpleBindRequest represents a username/password bind operation
 type SimpleBindRequest struct {
+	// Username is the name of the Directory object that the client wishes to bind as
 	Username string
+	// Password is the credentials to bind with
 	Password string
+	// Controls are optional controls to send with the bind request
 	Controls []Control
 }
 
+// SimpleBindResult contains the response from the server
 type SimpleBindResult struct {
 	Controls []Control
 }
 
+// NewSimpleBindRequest returns a bind request
 func NewSimpleBindRequest(username string, password string, controls []Control) *SimpleBindRequest {
 	return &SimpleBindRequest{
 		Username: username,
@@ -39,6 +45,7 @@ func (bindRequest *SimpleBindRequest) encode() *ber.Packet {
 	return request
 }
 
+// SimpleBind performs the simple bind operation defined in the given request
 func (l *Conn) SimpleBind(simpleBindRequest *SimpleBindRequest) (*SimpleBindResult, error) {
 	packet := ber.Encode(ber.ClassUniversal, ber.TypeConstructed, ber.TagSequence, nil, "LDAP Request")
 	packet.AppendChild(ber.NewInteger(ber.ClassUniversal, ber.TypePrimitive, ber.TagInteger, l.nextMessageID(), "MessageID"))
@@ -90,6 +97,7 @@ func (l *Conn) SimpleBind(simpleBindRequest *SimpleBindRequest) (*SimpleBindResu
 	return result, nil
 }
 
+// Bind performs a bind with the given username and password
 func (l *Conn) Bind(username, password string) error {
 	packet := ber.Encode(ber.ClassUniversal, ber.TypeConstructed, ber.TagSequence, nil, "LDAP Request")
 	packet.AppendChild(ber.NewInteger(ber.ClassUniversal, ber.TypePrimitive, ber.TagInteger, l.nextMessageID(), "MessageID"))

conn.go

@@ -17,18 +17,27 @@ import (
 )
 
 const (
-	MessageQuit     = 0
-	MessageRequest  = 1
+	// MessageQuit causes the processMessages loop to exit
+	MessageQuit = 0
+	// MessageRequest sends a request to the server
+	MessageRequest = 1
+	// MessageResponse receives a response from the server
 	MessageResponse = 2
-	MessageFinish   = 3
-	MessageTimeout  = 4
+	// MessageFinish indicates the client considers a particular message ID to be finished
+	MessageFinish = 3
+	// MessageTimeout indicates the client-specified timeout for a particular message ID has been reached
+	MessageTimeout = 4
 )
 
+// PacketResponse contains the packet or error encountered reading a response
 type PacketResponse struct {
+	// Packet is the packet read from the server
 	Packet *ber.Packet
-	Error  error
+	// Error is an error encountered while reading
+	Error error
 }
 
+// ReadPacket returns the packet or an error
 func (pr *PacketResponse) ReadPacket() (*ber.Packet, error) {
 	if (pr == nil) || (pr.Packet == nil && pr.Error == nil) {
 		return nil, NewError(ErrorNetwork, errors.New("ldap: could not retrieve response"))
@@ -37,8 +46,10 @@ func (pr *PacketResponse) ReadPacket() (*ber.Packet, error) {
 }
 
 type messageContext struct {
-	id        int64
-	done      chan struct{}
+	id int64
+	// close(done) should only be called from finishMessage()
+	done chan struct{}
+	// close(responses) should only be called from processMessages(), and only sent to from sendResponse()
 	responses chan *PacketResponse
 }
 
@@ -140,6 +151,7 @@ func NewConn(conn net.Conn, isTLS bool) *Conn {
 	}
 }
 
+// Start initializes goroutines to read responses and process messages
 func (l *Conn) Start() {
 	go l.reader()
 	go l.processMessages()
@@ -167,7 +179,7 @@ func (l *Conn) Close() {
 	l.wgClose.Wait()
 }
 
-// Sets the time after a request is sent that a MessageTimeout triggers
+// SetTimeout sets the time after a request is sent that a MessageTimeout triggers
 func (l *Conn) SetTimeout(timeout time.Duration) {
 	if timeout > 0 {
 		l.requestTimeout = timeout
@@ -253,15 +265,14 @@ func (l *Conn) sendMessageWithFlags(packet *ber.Packet, flags sendMessageFlags)
 	l.Debug.Printf("flags&startTLS = %d", flags&startTLS)
 	if l.isStartingTLS {
 		l.messageMutex.Unlock()
-		return nil, NewError(ErrorNetwork, errors.New("ldap: connection is in startls phase."))
+		return nil, NewError(ErrorNetwork, errors.New("ldap: connection is in startls phase"))
 	}
 	if flags&startTLS != 0 {
 		if l.outstandingRequests != 0 {
 			l.messageMutex.Unlock()
 			return nil, NewError(ErrorNetwork, errors.New("ldap: cannot StartTLS with outstanding requests"))
-		} else {
-			l.isStartingTLS = true
 		}
+		l.isStartingTLS = true
 	}
 	l.outstandingRequests++