dif: streamline Encoder/Decoder documentation

dif/const.go

+// Copyright 2020 The go-lpc Authors. All rights reserved.
+// Use of this source code is governed by a BSD-style
+// license that can be found in the LICENSE file.
+
+package dif
+
+const (
+	//	scHeader  = 0xb1 // slow-control header marker
+	//	scTrailer = 0xa1 // slow-control trailer marker
+
+	gbHeader  = 0xb0 // global header marker
+	gbHeaderB = 0xbb // global header marker (0xBB variant)
+	gbTrailer = 0xa0 // global trailer marker
+
+	frHeader  = 0xb4 // frame header marker
+	frTrailer = 0xa3 // frame trailer marker
+
+	anHeader = 0xc4 // analog frame header marker
+	incFrame = 0xc3 // incomplete frame marker
+)

dif/decoder.go

@@ -12,23 +12,8 @@ import (
 	"golang.org/x/xerrors"
 )
 
-const (
-	//	scHeader  = 0xb1 // slow-control header marker
-	//	scTrailer = 0xa1 // slow-control trailer marker
-
-	gbHeader  = 0xb0 // global header marker
-	gbHeaderB = 0xbb // global header marker (0xBB variant)
-	gbTrailer = 0xa0 // global trailer marker
-
-	frHeader  = 0xb4 // frame header marker
-	frTrailer = 0xa3 // frame trailer marker
-
-	anHeader = 0xc4 // analog frame header marker
-	incFrame = 0xc3 // incomplete frame marker
-)
-
-// Decoder reads (and validates) data from an underlying data source.
-// Decoder computes CRC-16 checksums on the fly, during the
+// Decoder reads and decodes DIF data from an input stream.
+// Decoder computes the CRC-16 checksums on the fly, during the
 // acquisition of DIF Frames.
 type Decoder struct {
 	r io.Reader
@@ -39,7 +24,7 @@ type Decoder struct {
 	crc crc16.Hash16
 }
 
-// NewDecoder creates a decoder that reads and validates data from r.
+// NewDecoder returns a new Decoder that reads from r.
 func NewDecoder(difID uint8, r io.Reader) *Decoder {
 	return &Decoder{
 		r:   r,
@@ -57,6 +42,8 @@ func (dec *Decoder) reset() {
 	dec.crc.Reset()
 }
 
+// Decode reads the next DIF data from its input stream and stores it
+// in the value pointed by dif.
 func (dec *Decoder) Decode(dif *DIF) error {
 	dec.reset()
 

dif/encoder.go

@@ -12,6 +12,9 @@ import (
 	"golang.org/x/xerrors"
 )
 
+// Encoder writes DIF data to an output stream.
+// Encoder computes the CRC-16 checksum on the fly and appends it
+// at the end of the stream.
 type Encoder struct {
 	w   io.Writer
 	buf []byte
@@ -19,6 +22,7 @@ type Encoder struct {
 	crc crc16.Hash16
 }
 
+// NewEncoder returns a new Encoder that writes to w.
 func NewEncoder(w io.Writer) *Encoder {
 	return &Encoder{
 		w:   w,
@@ -35,6 +39,8 @@ func (enc *Encoder) reset() {
 	enc.crc.Reset()
 }
 
+// Encode writes the DIF data to the stream, computes the corresponding
+// CRC-16 checksum on the fly and appends it to the stream.
 func (enc *Encoder) Encode(dif *DIF) error {
 	if dif == nil {
 		return nil