audio/internal/readerdriver: Refactoring for documentations

Updates #1779

audio/internal/readerdriver/driver.go

@@ -18,21 +18,92 @@ import (
 	"io"
 )
 
-type Context interface {
+// Context is the main object in Oto. It interacts with the audio drivers.
-	NewPlayer(io.Reader) Player
+//
-	Suspend() error
+// To play sound with Oto, first create a context. Then use the context to create
-	Resume() error
+// an arbitrary number of players. Then use the players to play sound.
+//
+// There can only be one context at any time. Closing a context and opening a new one is allowed.
+type Context struct {
+	context *context
 }
 
+// NewPlayer creates a new, ready-to-use Player belonging to the Context.
+//
+// The r's format is as follows:
+//   [data]      = [sample 1] [sample 2] [sample 3] ...
+//   [sample *]  = [channel 1] ...
+//   [channel *] = [byte 1] [byte 2] ...
+// Byte ordering is little endian.
+//
+// A player has some amount of an underlying buffer.
+// Read data from r is queued to the player's underlying buffer.
+// The underlying buffer is consumed by its playing.
+// Then, r's position and the current playing position don't necessarily match.
+// If you want to clear the underlying buffer for some reasons e.g., you want to seek the position of r,
+// call the player's Reset function.
+//
+// You cannot share r by multiple players.
+func (c *Context) NewPlayer(r io.Reader) Player {
+	return c.context.NewPlayer(r)
+}
+
+// Suspend suspends the entire audio play.
+func (c *Context) Suspend() error {
+	return c.context.Suspend()
+}
+
+// Resume resumes the entire audio play, which was suspended by Suspend.
+func (c *Context) Resume() error {
+	return c.context.Resume()
+}
+
+// NewContext creates a new context, that creates and holds ready-to-use Player objects,
+// and returns a context, a channel that is closed when the context is ready, and an error if it exists.
+//
+// The sampleRate argument specifies the number of samples that should be played during one second.
+// Usual numbers are 44100 or 48000.
+//
+// The channelNum argument specifies the number of channels. One channel is mono playback. Two
+// channels are stereo playback. No other values are supported.
+//
+// The bitDepthInBytes argument specifies the number of bytes per sample per channel. The usual value
+// is 2. Only values 1 and 2 are supported.
+func NewContext(sampleRate int, channelNum int, bitDepthInBytes int) (*Context, chan struct{}, error) {
+	ctx, ready, err := newContext(sampleRate, channelNum, bitDepthInBytes)
+	if err != nil {
+		return nil, nil, err
+	}
+	return &Context{context: ctx}, ready, nil
+}
+
+// Player is a PCM (pulse-code modulation) audio player.
 type Player interface {
+	// Pause pauses its playing.
 	Pause()
+
+	// Play starts its playing if it doesn't play.
 	Play()
+
+	// IsPlaying reports whether this player is playing.
 	IsPlaying() bool
+
+	// Reset clears the underyling buffer and pauses its playing.
 	Reset()
+
+	// Volume returns the current volume in between [0, 1].
+	// The default volume is 1.
 	Volume() float64
+
+	// SetVolume sets the current volume in between [0, 1].
 	SetVolume(volume float64)
+
+	// UnplayedBufferSize returns the byte size in the underlying buffer that is not played yet.
 	UnplayedBufferSize() int
+
+	// Err returns an error if this player has an error.
 	Err() error
+
 	io.Closer
 }
 

audio/internal/readerdriver/driver_android.go

@@ -26,7 +26,7 @@ type context struct {
 	players *players
 }
 
-func NewContext(sampleRate int, channelNum int, bitDepthInBytes int) (Context, chan struct{}, error) {
+func newContext(sampleRate int, channelNum int, bitDepthInBytes int) (*context, chan struct{}, error) {
 	ready := make(chan struct{})
 	close(ready)
 

audio/internal/readerdriver/driver_darwin.go

@@ -89,7 +89,7 @@ type context struct {
 
 var theContext *context
 
-func NewContext(sampleRate, channelNum, bitDepthInBytes int) (Context, chan struct{}, error) {
+func newContext(sampleRate, channelNum, bitDepthInBytes int) (*context, chan struct{}, error) {
 	ready := make(chan struct{})
 	close(ready)
 

audio/internal/readerdriver/driver_js.go

@@ -36,7 +36,7 @@ type context struct {
 	bitDepthInBytes int
 }
 
-func NewContext(sampleRate int, channelNum int, bitDepthInBytes int) (Context, chan struct{}, error) {
+func newContext(sampleRate int, channelNum int, bitDepthInBytes int) (*context, chan struct{}, error) {
 	ready := make(chan struct{})
 	if js.Global().Get("go2cpp").Truthy() {
 		close(ready)

audio/internal/readerdriver/driver_unix.go

@@ -50,7 +50,7 @@ func alsaError(err C.int) error {
 	return fmt.Errorf("readerdriver: ALSA error: %s", C.GoString(C.snd_strerror(err)))
 }
 
-func NewContext(sampleRate, channelNum, bitDepthInBytes int) (Context, chan struct{}, error) {
+func newContext(sampleRate, channelNum, bitDepthInBytes int) (*context, chan struct{}, error) {
 	ready := make(chan struct{})
 	close(ready)
 

audio/internal/readerdriver/driver_windows.go

@@ -78,7 +78,7 @@ type context struct {
 
 var theContext *context
 
-func NewContext(sampleRate, channelNum, bitDepthInBytes int) (Context, chan struct{}, error) {
+func newContext(sampleRate, channelNum, bitDepthInBytes int) (*context, chan struct{}, error) {
 	ready := make(chan struct{})
 	close(ready)
 

audio/player.go

@@ -23,14 +23,20 @@ import (
 	"github.com/hajimehoshi/ebiten/v2/audio/internal/readerdriver"
 )
 
+type context interface {
+	NewPlayer(io.Reader) readerdriver.Player
+	Suspend() error
+	Resume() error
+}
+
 type playerFactory struct {
-	context    readerdriver.Context
+	context    context
 	sampleRate int
 
 	m sync.Mutex
 }
 
-var driverForTesting readerdriver.Context
+var driverForTesting context
 
 func newPlayerFactory(sampleRate int) *playerFactory {
 	f := &playerFactory{