doc for port

common/net/port.go

@@ -12,12 +12,17 @@ var (
 	ErrorInvalidPortRange = errors.New("Invalid port range.")
 )
 
+// Port represents a network port in TCP and UDP protocol.
 type Port serial.Uint16Literal
 
+// PortFromBytes converts a byte array to a Port, assuming bytes are in big endian order.
+// @unsafe Caller must ensure that the byte array has at least 2 elements.
 func PortFromBytes(port []byte) Port {
 	return Port(serial.BytesLiteral(port).Uint16Value())
 }
 
+// PortFromInt converts an integer to a Port.
+// @error when the integer is not positive or larger then 65535
 func PortFromInt(v int) (Port, error) {
 	if v <= 0 || v > 65535 {
 		return Port(0), ErrorInvalidPortRange
@@ -25,6 +30,8 @@ func PortFromInt(v int) (Port, error) {
 	return Port(v), nil
 }
 
+// PortFromString converts a string to a Port.
+// @error when the string is not an integer or the integral value is a not a valid Port.
 func PortFromString(s string) (Port, error) {
 	v, err := strconv.Atoi(s)
 	if err != nil {
@@ -33,23 +40,28 @@ func PortFromString(s string) (Port, error) {
 	return PortFromInt(v)
 }
 
+// Value return the correspoding uint16 value of this Port.
 func (this Port) Value() uint16 {
 	return uint16(this)
 }
 
+// Bytes returns the correspoding bytes of this Port, in big endian order.
 func (this Port) Bytes() []byte {
 	return serial.Uint16Literal(this).Bytes()
 }
 
+// String returns the string presentation of this Port.
 func (this Port) String() string {
 	return serial.Uint16Literal(this).String()
 }
 
+// PortRange represents a range of ports.
 type PortRange struct {
 	From Port
 	To   Port
 }
 
+// Contains returns true if the given port is within the range of this PortRange.
 func (this PortRange) Contains(port Port) bool {
 	return this.From <= port && port <= this.To
 }