From ebedb24e43d2c9e2b6adf70fe4b6e679befb71c1 Mon Sep 17 00:00:00 2001
From: Hajime Hoshi <hajimehoshi@gmail.com>
Date: Wed, 5 Apr 2017 01:12:02 +0900
Subject: [PATCH] audio: Update doc for errors (#331)

---
 audio/audio.go | 18 +++++++++++++++++-
 1 file changed, 17 insertions(+), 1 deletion(-)

diff --git a/audio/audio.go b/audio/audio.go
index 351bb10a1..dd000b3d1 100644
--- a/audio/audio.go
+++ b/audio/audio.go
@@ -200,11 +200,15 @@ var (
 )
 
 // NewContext creates a new audio context with the given sample rate (e.g. 44100).
+//
+// Error returned by NewContext is always nil as of 1.5.0-alpha.
+//
+// NewContext panics when an audio context is already created.
 func NewContext(sampleRate int) (*Context, error) {
 	theContextLock.Lock()
 	defer theContextLock.Unlock()
 	if theContext != nil {
-		return nil, errors.New("audio: context is already created")
+		panic("audio: context is already created")
 	}
 	c := &Context{
 		sampleRate: sampleRate,
@@ -225,6 +229,8 @@ func NewContext(sampleRate int) (*Context, error) {
 // In sync mode, the game logical time syncs the audio logical time and
 // you will find audio stops when the game stops e.g. when the window is deactivated.
 // In async mode, the audio never stops even when the game stops.
+//
+// Update returns error when IO error occurs.
 func (c *Context) Update() error {
 	// Initialize c.driver lazily to enable calling NewContext in an 'init' function.
 	// Accessing driver functions requires the environment to be already initialized,
@@ -356,6 +362,8 @@ func NewPlayerFromBytes(context *Context, src []byte) (*Player, error) {
 //
 // When closing, the stream owned by the player will also be closed by calling its Close.
 //
+// Close returns error when closing the source returns error.
+//
 // This function is concurrent-safe.
 func (p *Player) Close() error {
 	p.players.removePlayer(p)
@@ -392,6 +400,8 @@ func (p *Player) bufferLength() int {
 
 // Play plays the stream.
 //
+// Play always returns nil.
+//
 // This function is concurrent-safe.
 func (p *Player) Play() error {
 	p.players.addPlayer(p)
@@ -407,6 +417,8 @@ func (p *Player) IsPlaying() bool {
 
 // Rewind rewinds the current position to the start.
 //
+// Rewind returns error when seeking the source returns error.
+//
 // This function is concurrent-safe.
 func (p *Player) Rewind() error {
 	return p.Seek(0)
@@ -414,6 +426,8 @@ func (p *Player) Rewind() error {
 
 // Seek seeks the position with the given offset.
 //
+// Seek returns error when seeking the source returns error.
+//
 // This function is concurrent-safe.
 func (p *Player) Seek(offset time.Duration) error {
 	p.players.addSeeking(p)
@@ -431,6 +445,8 @@ func (p *Player) Seek(offset time.Duration) error {
 
 // Pause pauses the playing.
 //
+// Pause always returns nil.
+//
 // This function is concurrent-safe.
 func (p *Player) Pause() error {
 	p.players.removePlayer(p)