nslcd_proto: Add some doc comments

1 files changed, 13 insertions, 1 deletions

diff --git a/nslcd_proto/io.go b/nslcd_proto/io.go
index 9252aca..a2adade 100644
--- a/nslcd_proto/io.go
+++ b/nslcd_proto/io.go
@@ -1,4 +1,4 @@
-// Copyright (C) 2015 Luke Shumaker <lukeshu@sbcglobal.net>
+// Copyright (C) 2015, 2017 Luke Shumaker <lukeshu@sbcglobal.net>
 //
 // This library is free software; you can redistribute it and/or
 // modify it under the terms of the GNU Lesser General Public
@@ -27,17 +27,29 @@ import (
 	"golang.org/x/sys/unix"
 )
 
+// NslcdError represents a normal, expected error when dealing with
+// the nslcd protocol.  Passing invalid data to a Write operation is
+// *not* an NslcdError, nor is passing a non-pointer to a Read
+// operation; those are programming errors, and result in a panic().
 type NslcdError string
 
 func (o NslcdError) Error() string {
 	return string(o)
 }
 
+// An nslcdObject is an object with a different network representation
+// than a naive structure.
 type nslcdObject interface {
+	// May panic(interface{}) if given invalid data.
+	//
+	// May panic(NslcdError) if encountering a network error.
 	nslcdWrite(fd io.Writer)
 }
 
+// An nslcdObjectPtr is a pointer to an object with a different
+// network representation than a naive structure.
 type nslcdObjectPtr interface {
+	// May panic(NslcdError) if encountering a network error.
 	nslcdRead(fd io.Reader)
 }