Enhancements for GoDocs

docs.go

@@ -22,4 +22,9 @@ package sdk
 import (
 	_ "github.com/deepgram/deepgram-go-sdk/pkg/client/live"
 	_ "github.com/deepgram/deepgram-go-sdk/pkg/client/prerecorded"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/client/rest"
+
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/live/v1"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/manage/v1"
+	_ "github.com/deepgram/deepgram-go-sdk/pkg/api/prerecorded/v1"
 )

examples/README.md

@@ -20,16 +20,22 @@ go mod tidy
 
 ### Set your API Key as an Environment Variable named "DEEPGRAM_API_KEY"
 
-If using bash, this could be done in your `.bash_profile` or this could also be done by a simple export seen below.
+If using bash, this could be done in your `~/.bash_profile` like so:
 
 ```bash
 export DEEPGRAM_API_KEY = "YOUR_DEEPGRAM_API_KEY"
 ```
 
+or this could also be done by a simple export before executing your Go application:
+
+```bash
+DEEPGRAM_API_KEY="YOUR_DEEPGRAM_API_KEY" go run main.go
+```
+
 ### Run the project
 
-Make sure you're in the directory with the `main.go` file and run the project with the following command.
+If you chose to set an environment variable in your shell profile (ie `.bash_profile`) you can change directory into each example folder and run the example like so:
 
-```
+```bash
 go run main.go
 ```

examples/manage/invitations/main.go

@@ -85,7 +85,7 @@ func main() {
 		}
 	}
 
-	// delete project
+	// delete invitation
 	respMessage, err = mgClient.DeleteInvitation(ctx, projectId, "[email protected]")
 	if err != nil {
 		log.Printf("DeleteInvitation failed. Err: %v\n", err)

examples/manage/keys/main.go

@@ -85,15 +85,15 @@ func main() {
 	}
 	log.Printf("GetKey() - ID: %s, Comment: %s\n", respKey.APIKey.APIKeyID, respKey.APIKey.Comment)
 
-	// delete project
+	// delete key
 	respMessage, err := mgClient.DeleteKey(ctx, projectId, respKey.APIKey.APIKeyID)
 	if err != nil {
 		log.Printf("DeleteKey failed. Err: %v\n", err)
 		os.Exit(1)
 	}
 	log.Printf("DeleteKey() - Name: %s\n", respMessage.Message)
 
-	// list invitations
+	// list keys
 	respGet, err = mgClient.ListKeys(ctx, projectId)
 	if err != nil {
 		log.Printf("ListKeys failed. Err: %v\n", err)

examples/streaming/http/main.go

@@ -25,29 +25,30 @@ func main() {
 	// init library
 	client.InitWithDefault()
 
-	// context
+	// Go context
 	ctx := context.Background()
 
-	// options
+	// set the Transcription options
 	transcriptOptions := interfaces.LiveTranscriptionOptions{
 		Language:  "en-US",
 		Punctuate: true,
 	}
 
+	// create a Deepgram client
 	dgClient, err := client.NewForDemo(ctx, transcriptOptions)
 	if err != nil {
 		log.Println("ERROR creating LiveTranscription connection:", err)
 		return
 	}
 
-	// call connect!
+	// connect the websocket to Deepgram
 	wsconn := dgClient.Connect()
 	if wsconn == nil {
 		log.Println("Client.Connect failed")
 		os.Exit(1)
 	}
 
-	// feed the stream to the websocket
+	// get the HTTP stream
 	httpClient := new(http.Client)
 
 	res, err := httpClient.Get(STREAM_URL)
@@ -58,8 +59,8 @@ func main() {
 
 	log.Printf("Stream is up and running %s\n", reflect.TypeOf(res))
 
-	// this is a blocking call...
 	go func() {
+		// feed the HTTP stream to the Deepgram client (this is a blocking call)
 		dgClient.Stream(bufio.NewReader(res.Body))
 	}()
 

examples/streaming/microphone/main.go

@@ -107,7 +107,7 @@ func main() {
 	}
 
 	go func() {
-		// this is a blocking call
+		// feed the microphone stream to the Deepgram client (this is a blocking call)
 		mic.Stream(dgClient)
 	}()
 

examples/streaming/replay/main.go

@@ -69,7 +69,7 @@ func main() {
 	}
 
 	go func() {
-		// this is a blocking call
+		// feed the WAV stream to the Deepgram client (this is a blocking call)
 		play.Stream(dgClient)
 	}()
 

pkg/api/live/v1/interfaces/constants.go

@@ -4,6 +4,7 @@
 
 package interfaces
 
+// These are the message types that can be received from the live API
 const (
 	// message types
 	TypeMessageResponse  string = "Results"

pkg/api/live/v1/interfaces/interfaces.go

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
+// This package defines interfaces for the live API
 package interfaces
 
 // LiveMessageCallback is a callback used to receive notifcations for platforms messages

pkg/api/live/v1/router.go

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
+// This package defines the live API for Deepgram
 package live
 
 import (

pkg/api/manage/v1/balances.go

@@ -3,9 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 /*
-This package contains the code for the Balances APIs in the Deepgram Manage API
-
-Please see:
+Balances API:
 https://developers.deepgram.com/reference/get-all-balances
 https://developers.deepgram.com/reference/get-balance
 */

pkg/api/manage/v1/constants.go

@@ -2,9 +2,6 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-/*
-This package contains the code for the Deepgram Manage API Balances endpoint.
-*/
 package manage
 
 import (

pkg/api/manage/v1/docs.go

@@ -0,0 +1,8 @@
+// Copyright 2023 Deepgram SDK contributors. All Rights Reserved.
+// Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+// SPDX-License-Identifier: MIT
+
+/*
+This package contains the code for the Keys APIs in the Deepgram Manage API
+*/
+package manage

pkg/api/manage/v1/invitations.go

@@ -3,9 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 /*
-This package contains the code for the Invitations APIs in the Deepgram Manage API
-
-Please see:
+Invitations API
 https://developers.deepgram.com/reference/list-invites
 https://developers.deepgram.com/reference/send-invites
 https://developers.deepgram.com/reference/delete-invite

pkg/api/manage/v1/keys.go

@@ -3,9 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 /*
-This package contains the code for the Keys APIs in the Deepgram Manage API
-
-Please see:
+Keys API:
 https://developers.deepgram.com/reference/list-keys
 https://developers.deepgram.com/reference/get-key
 https://developers.deepgram.com/reference/create-key

pkg/api/manage/v1/manage.go

@@ -2,9 +2,6 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-/*
-This package contains the code for the Keys APIs in the Deepgram Manage API
-*/
 package manage
 
 import (

pkg/api/manage/v1/members.go

@@ -3,9 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 /*
-This package contains the code for the Members APIs in the Deepgram Manage API
-
-Please see:
+Members API:
 https://developers.deepgram.com/reference/get-members
 https://developers.deepgram.com/reference/remove-member
 */

pkg/api/manage/v1/projects.go

@@ -3,9 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 /*
-This package contains the code for the Projects APIs in the Deepgram Manage API
-
-Please see:
+Projects API:
 https://developers.deepgram.com/reference/get-projects
 https://developers.deepgram.com/reference/get-project
 https://developers.deepgram.com/reference/update-project

pkg/api/manage/v1/scopes.go

@@ -3,9 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 /*
-This package contains the code for the Scopes APIs in the Deepgram Manage API
-
-Please see:
+Scopes API:
 https://developers.deepgram.com/reference/get-member-scopes
 https://developers.deepgram.com/reference/update-scope
 */

pkg/api/manage/v1/usage.go

@@ -3,9 +3,7 @@
 // SPDX-License-Identifier: MIT
 
 /*
-This package contains the code for the Usage APIs in the Deepgram Manage API
-
-Please see:
+Usage API:
 https://developers.deepgram.com/reference/get-all-requests
 https://developers.deepgram.com/reference/get-request
 https://developers.deepgram.com/reference/summarize-usage

pkg/api/prerecorded/v1/constants.go

@@ -8,6 +8,7 @@ import (
 	"errors"
 )
 
+// errors
 var (
 	// ErrInvalidInput required input was not found
 	ErrInvalidInput = errors.New("required input was not found")

pkg/api/prerecorded/v1/interfaces/types.go

@@ -2,9 +2,6 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-/*
-This package provides the types for the Deepgram PreRecorded API.
-*/
 package interfaces
 
 /***********************************/

pkg/api/prerecorded/v1/prerecorded.go

@@ -2,6 +2,7 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
+// This package defines the Pre-recorded API for Deepgram
 package prerecorded
 
 import (

pkg/api/version/constants.go

@@ -2,7 +2,6 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-// This package handles the versioning in the API for live/streaming transcription
 package version
 
 import "errors"

pkg/api/version/live-version.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-// This package handles the versioning in the API for live/streaming transcription
+// This package handles the versioning in the API for live/streaming websocket
 package version
 
 import (

pkg/api/version/manage-version.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-// This package handles the versioning in the API for live/streaming transcription
+// This package handles the versioning in the API for manage endpoints
 package version
 
 import (

pkg/api/version/prerecorded-version.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-// This package handles the versioning in the API for live/streaming transcription
+// This package handles the versioning in the API for prerecorded endpoint
 package version
 
 import (

pkg/audio/microphone/constants.go

@@ -2,7 +2,6 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-// Implementation microphone using portaudio
 package microphone
 
 const (

pkg/audio/microphone/microphone.go

@@ -2,7 +2,7 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-// Implementation microphone using portaudio
+// Implementation of a microphone using portaudio
 package microphone
 
 import (
@@ -15,15 +15,15 @@ import (
 	klog "k8s.io/klog/v2"
 )
 
-// Initialize inits the library
+// Initialize inits the library. This handles OS level init of the library.
 func Initialize() {
 	err := portaudio.Initialize()
 	if err != nil {
 		klog.V(1).Infof("portaudio.Initialize failed. Err: %v\n", err)
 	}
 }
 
-// Teardown cleans up the library
+// Teardown cleans up the library. This handles OS level cleanup.
 func Teardown() {
 	err := portaudio.Terminate()
 	if err != nil {

pkg/audio/microphone/types.go

@@ -2,7 +2,6 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-// Implementation microphone using portaudio
 package microphone
 
 import (

pkg/audio/replay/constants.go

@@ -2,17 +2,18 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-// Implementation for a replay device. In this case, replays an audio file to stream into a listener
 package replay
 
 import (
 	"errors"
 )
 
+// constants
 const (
 	defaultBytesToRead int = 2048
 )
 
+// errors
 var (
 	// ErrInvalidInput required input was not found
 	ErrInvalidInput = errors.New("required input was not found")

pkg/audio/replay/types.go

@@ -2,7 +2,6 @@
 // Use of this source code is governed by a MIT license that can be found in the LICENSE file.
 // SPDX-License-Identifier: MIT
 
-// Implementation for a replay device. In this case, replays an audio file to stream into a listener
 package replay
 
 import (

pkg/client/interfaces/docs.go

@@ -0,0 +1,8 @@
+// Copyright 2023 Deepgram SDK contributors. All Rights Reserved.
+// Use of this source code is governed by a MIT license that can be found in the LICENSE file.
+// SPDX-License-Identifier: MIT
+
+/*
+This package contains the interface to manage the prerecorded and live/stream interfaces for the Deepgram API
+*/
+package interfaces