conn: Improve documentation

Explains the 'Bus → Port → Conn' concept that I had failed to put into words up to now

No code change.

conn/conn.go

@@ -24,7 +24,7 @@ const (
 	// Full means that communication occurs simultaneously both ways in a
 	// synchronized manner.
 	//
-	// Examples include SPI (except rare variants).
+	// Examples include SPI (except 3-wire variant).
 	Full Duplex = 2
 )
 
@@ -43,18 +43,21 @@ func (i Duplex) String() string {
 // communication channel.
 //
 // The connection can either be unidirectional (read-only, write-only) or
-// bidirectional (read-write). The connection can either be half-duplex or full
-// duplex.
+// bidirectional (read-write). It can either be half-duplex or full duplex.
 //
 // This is the lowest common denominator for all point-to-point communication
 // channels.
 //
-// Implementation are expected to also implement the following interfaces:
+// Implementation are expected but not required to also implement the following
+// interfaces:
+//
 // - fmt.Stringer which returns something meaningful to the user like "SPI0.1",
-//   "I2C1.76", "COM6", etc.
-// - io.Reader and io.Writer as an way to use io.Copy() on a read-only or
-//   write-only device. For example the FLIR Lepton is a read-only device, the
-//   SSD1306 is a write-only device.
+// "I2C1.76", "COM6", etc.
+//
+// - io.Reader and io.Writer as a way to use io.Copy() for half duplex
+// operation.
+//
+// - io.Closer for the owner of the communication channel.
 type Conn interface {
 	// Tx does a single transaction.
 	//

conn/conn_test.go

@@ -4,7 +4,23 @@
 
 package conn
 
-import "testing"
+import (
+	"log"
+	"testing"
+)
+
+func ExampleConn() {
+	// Get a connection from one of the registries, for example:
+	//   b, _ := spireg.Open("SPI0.0")
+	//   c, _ := b.DevParams(1000000, spi.Mode3, 8)
+	var c Conn
+
+	// Send a command over the connection without reading.
+	cmd := []byte("command")
+	if err := c.Tx(cmd, nil); err != nil {
+		log.Fatal(err)
+	}
+}
 
 func TestDuplex(t *testing.T) {
 	if Half.String() != "Half" || Duplex(10).String() != "Duplex(10)" {

conn/doc.go

@@ -4,6 +4,63 @@
 
 // Package conn defines core interfaces for protocols and connections.
 //
-// Subpackages implements all the interfaces that can be used to connects
-// peripherals.
+// This package and its subpackages describe the base interfaces to connect the
+// software with the real world. It doesn't contain any implementation but
+// includes registries to enable the application to discover the available
+// hardware.
+//
+// Concepts
+//
+// periph uses 3 layered concepts for interfacing:
+//
+//     Bus → Port → Conn
+//
+// Not every subpackage expose all 3 concepts. In fact, most packages don't.
+// For example, SPI doesn't expose Bus as the OSes generally only expose the
+// Port, that is, a Chip Select (CS) line must be selected right upfront to get
+// an handle.  For I²C, there's no Port to configure, so selecting a "slave"
+// address is sufficient to jump directly from a Bus to a Conn.
+//
+// periph doesn't have yet a concept of star-like communication network, like
+// an IP network.
+//
+// Bus
+//
+// A Bus is a multi-point communication channel where one "master" and multiple
+// "slaves" communicate together. In the case of periph, the Bus handle is
+// assumed to be the "master". The "master" generally initiates communications
+// and selects the "slave" to talk to.
+//
+// As the "master" selects a "slave" over a bus, a virtual Port is
+// automatically created.
+//
+// Examples include SPI, I²C and 1-wire. In each case, selecting a
+// communication line (Chip Select (CS) line for SPI, address for I²C or
+// 1-wire) converts the Bus into a Port.
+//
+// Port
+//
+// A port is a point-to-point communication channel that is yet to be
+// initialized. It cannot be used for communication until it is connected and
+// transformed into a Conn. Configuring a Port converts it into a Conn. Not all
+// Port need configuration.
+//
+// Conn
+//
+// A Conn is a fully configured half or full duplex communication channel that
+// is point-to-point, only between two devices. It is ready to use like any
+// readable and/or writable pipe.
+//
+// Subpackages
+//
+// Most connection-type specific subpackages include subpackages:
+//
+// - XXXreg: registry as that is populated by the host drivers and that can be
+// leveraged by applications.
+//
+// - XXXtest: fake implementation that can be leveraged when writting device
+// driver unit test.
+//
+// - XXXsmoketest: smoke test that tests against real hardware to ensure the
+// whole stack work correctly, including the OS supplied drivers.
 package conn