@@ -27,6 +27,7 @@ type volumeEventLogger interface {

 }

 // VolumesService manages access to volumes

+// This is used as the main access point for volumes to higher level services and the API.

 type VolumesService struct {

 	vs           *VolumeStore

 	ds           ds

@@ -54,6 +55,12 @@ func (s *VolumesService) GetDriverList() []string {

 }

 // Create creates a volume

+// If the caller is creating this volume to be consumed immediately, it is

+// expected that the caller specifies a reference ID.

+// This reference ID will protect this volume from removal.

+//

+// A good example for a reference ID is a container's ID.

+// When whatever is going to reference this volume is removed the caller should defeference the volume by calling `Release`.

 func (s *VolumesService) Create(ctx context.Context, name, driverName string, opts ...opts.CreateOption) (*types.Volume, error) {

 	if name == "" {

 		name = stringid.GenerateNonCryptoID()

@@ -68,7 +75,7 @@ func (s *VolumesService) Create(ctx context.Context, name, driverName string, op

 	return &apiV, nil

 }

-// Get gets a volume

+// Get returns details about a volume

 func (s *VolumesService) Get(ctx context.Context, name string, getOpts ...opts.GetOption) (*types.Volume, error) {

 	v, err := s.vs.Get(ctx, name, getOpts...)

 	if err != nil {

@@ -88,6 +95,14 @@ func (s *VolumesService) Get(ctx context.Context, name string, getOpts ...opts.G

 }

 // Mount mounts the volume

+// Callers should specify a uniqe reference for each Mount/Unmount pair.

+//

+// Example:

+// ```go

+// mountID := "randomString"

+// s.Mount(ctx, vol, mountID)

+// s.Unmount(ctx, vol, mountID)

+// ```

 func (s *VolumesService) Mount(ctx context.Context, vol *types.Volume, ref string) (string, error) {

 	v, err := s.vs.Get(ctx, vol.Name, opts.WithGetDriver(vol.Driver))

 	if err != nil {

@@ -101,6 +116,10 @@ func (s *VolumesService) Mount(ctx context.Context, vol *types.Volume, ref strin

 // Unmount unmounts the volume.

 // Note that depending on the implementation, the volume may still be mounted due to other resources using it.

+//

+// The reference specified here should be the same reference specified during `Mount` and should be

+// unique for each mount/unmount pair.

+// See `Mount` documentation for an example.

 func (s *VolumesService) Unmount(ctx context.Context, vol *types.Volume, ref string) error {

 	v, err := s.vs.Get(ctx, vol.Name, opts.WithGetDriver(vol.Driver))

 	if err != nil {

@@ -118,6 +137,7 @@ func (s *VolumesService) Release(ctx context.Context, name string, ref string) e

 }

 // Remove removes a volume

+// An error is returned if the volume is still referenced.

 func (s *VolumesService) Remove(ctx context.Context, name string, rmOpts ...opts.RemoveOption) error {

 	var cfg opts.RemoveConfig

 	for _, o := range rmOpts {

@@ -182,7 +182,7 @@ func (s *VolumeStore) purge(ctx context.Context, name string) error {

 	return nil

 }

-// VolumeStore is a struct that stores the list of volumes available and keeps track of their usage counts

+// VolumeStore is responsible for storing and reference counting volumes.

 type VolumeStore struct {

 	// locks ensures that only one action is being performed on a particular volume at a time without locking the entire store

 	// since actions on volumes can be quite slow, this ensures the store is free to handle requests for other volumes.