Package documentation fixed

This adds and updates the package documentation.
Also some examples have been added to the documentation.

types.go

@@ -4,19 +4,38 @@ import (
 	"time"
 )
 
+// CredentialPersistence describes one of three persistence modes of a credential.
+// A detailed description of the available modes can be found on
+// MSDN: https://msdn.microsoft.com/en-us/library/windows/desktop/aa374788(v=vs.85).aspx
 type CredentialPersistence uint32
 
 const (
-	PersistSession      CredentialPersistence = 0x1
+	// PersistSession indicates that the credential only persists for the life
+	// of the current Windows login session. Such a credential is not visible in
+	// any other logon session, even from the same user.
+	PersistSession CredentialPersistence = 0x1
+
+	// PersistLocalMachine indicates that the credential persists for this and
+	// all subsequent logon sessions on this local machine/computer. It is
+	// however not visible for logon sessions of this user on a different
+	// machine.
 	PersistLocalMachine CredentialPersistence = 0x2
-	PersistEnterprise   CredentialPersistence = 0x3
+
+	// PersistEnterprise indicates that the credential persists for this and all
+	// subsequent logon sessions for this user. It is also visible for logon
+	// sessions on different computers.
+	PersistEnterprise CredentialPersistence = 0x3
 )
 
+// CredentialAttribute represents an application-specific attribute of a credential.
 type CredentialAttribute struct {
 	Keyword string
 	Value   []byte
 }
 
+// Credential is the basic credential structure.
+// A credential is identified by its target name.
+// The actual credential secret is available in the CredentialBlob field.
 type Credential struct {
 	TargetName     string
 	Comment        string
@@ -28,10 +47,23 @@ type Credential struct {
 	Persist        CredentialPersistence
 }
 
+// GenericCredential holds a credential for generic usage.
+// It is typically defined and used by applications that need to manage user
+// secrets.
+//
+// More information about the available kinds of credentials of the Windows
+// Credential Management API can be found on MSDN:
+// https://msdn.microsoft.com/en-us/library/windows/desktop/aa380517(v=vs.85).aspx
 type GenericCredential struct {
 	Credential
 }
 
+// DomainPassword holds a domain credential that is typically used by the
+// operating system for user logon.
+//
+// More information about the available kinds of credentials of the Windows
+// Credential Management API can be found on MSDN:
+// https://msdn.microsoft.com/en-us/library/windows/desktop/aa380517(v=vs.85).aspx
 type DomainPassword struct {
 	Credential
 }

wincred.go

@@ -1,10 +1,16 @@
+// Package wincred provides primitives for accessing the Windows Credentials Management API.
+// This includes functions for retrieval, listing and storage of credentials as well as Go structures for convenient access to the credential data.
+//
+// A more detailed description of Windows Credentials Management can be found on
+// MSDN: https://msdn.microsoft.com/en-us/library/windows/desktop/aa374789(v=vs.85).aspx
 package wincred
 
 import (
 	"syscall"
 )
 
-// Get the generic credential with the given name from Windows credential manager
+// GetGenericCredential fetches the generic credential with the given name from Windows credential manager.
+// It returns nil and an error if the credential could not be found or an error occurred.
 func GetGenericCredential(targetName string) (*GenericCredential, error) {
 	cred, err := nativeCredRead(targetName, naCRED_TYPE_GENERIC)
 	if cred != nil {
@@ -13,27 +19,30 @@ func GetGenericCredential(targetName string) (*GenericCredential, error) {
 	return nil, err
 }
 
-// Create a new generic credential with the given name
+// NewGenericCredential creates a new generic credential object with the given name.
+// The persist mode of the newly created object is set to a default value that indicates local-machine-wide storage.
+// The credential object is NOT yet persisted to the Windows credential vault.
 func NewGenericCredential(targetName string) (result *GenericCredential) {
 	result = new(GenericCredential)
 	result.TargetName = targetName
 	result.Persist = PersistLocalMachine
 	return
 }
 
-// Persist the credential to Windows credential manager
+// Write persists the generic credential object to Windows credential manager.
 func (t *GenericCredential) Write() (err error) {
 	err = nativeCredWrite(&t.Credential, naCRED_TYPE_GENERIC)
 	return
 }
 
-// Delete the credential from Windows credential manager
+// Delete removes the credential object from Windows credential manager.
 func (t *GenericCredential) Delete() (err error) {
 	err = nativeCredDelete(&t.Credential, naCRED_TYPE_GENERIC)
 	return
 }
 
-// Get the domain password credential with the given target host name
+// GetDomainPassword fetches the domain-password credential with the given target host name from Windows credential manager.
+// It returns nil and an error if the credential could not be found or an error occurred.
 func GetDomainPassword(targetName string) (*DomainPassword, error) {
 	cred, err := nativeCredRead(targetName, naCRED_TYPE_DOMAIN_PASSWORD)
 	if cred != nil {
@@ -42,33 +51,34 @@ func GetDomainPassword(targetName string) (*DomainPassword, error) {
 	return nil, err
 }
 
-// Create a new domain password credential used for login to the given target host name
+// NewDomainPassword creates a new domain-password credential used for login to the given target host name.
+// The  persist mode of the newly created object is set to a default value that indicates local-machine-wide storage.
+// The credential object is NOT yet persisted to the Windows credential vault.
 func NewDomainPassword(targetName string) (result *DomainPassword) {
 	result = new(DomainPassword)
 	result.TargetName = targetName
 	result.Persist = PersistLocalMachine
 	return
 }
 
-// Persist the domain password credential to Windows credential manager
+// Write persists the domain-password credential to Windows credential manager.
 func (t *DomainPassword) Write() (err error) {
 	err = nativeCredWrite(&t.Credential, naCRED_TYPE_DOMAIN_PASSWORD)
 	return
 }
 
-// Delete the domain password credential from Windows credential manager
+// Delete removes the domain-password credential from Windows credential manager.
 func (t *DomainPassword) Delete() (err error) {
 	err = nativeCredDelete(&t.Credential, naCRED_TYPE_DOMAIN_PASSWORD)
 	return
 }
 
-// Set the CredentialBlob field of a domain password credential
-// using an UTF16 encoded password string
+// SetPassword sets the CredentialBlob field of a domain password credential to the given string.
 func (t *DomainPassword) SetPassword(pw string) {
 	t.CredentialBlob = utf16ToByte(syscall.StringToUTF16(pw))
 }
 
-// List the contents of the Credentials store
+// List retrieves all credentials of the Credentials store.
 func List() ([]*Credential, error) {
 	creds, err := nativeCredEnumerate("", true)
 	if err != nil && err.Error() == naERROR_NOT_FOUND {

wincred_test.go

@@ -1,6 +1,7 @@
 package wincred
 
 import (
+	"fmt"
 	"testing"
 
 	"github.com/stretchr/testify/assert"
@@ -86,3 +87,32 @@ func TestGenericCredential_DeleteNotFound(t *testing.T) {
 	// MSDN: https://msdn.microsoft.com/en-us/library/windows/desktop/ms681383(v=vs.85).aspx
 	assert.Equal(t, "Element not found.", err.Error())
 }
+
+func ExampleList() {
+	if creds, err := List(); err == nil {
+		for _, cred := range creds {
+			fmt.Println(cred.TargetName)
+		}
+	}
+}
+
+func ExampleGetGenericCredential() {
+	if cred, err := GetGenericCredential("myGoApplication"); err == nil {
+		fmt.Println(cred.TargetName, string(cred.CredentialBlob))
+	}
+}
+
+func ExampleGenericCredential_Delete() {
+	cred, _ := GetGenericCredential("myGoApplication")
+	if err := cred.Delete(); err == nil {
+		fmt.Println("Deleted")
+	}
+}
+
+func ExampleGenericCredential_Write() {
+	cred := NewGenericCredential("myGoApplication")
+	cred.CredentialBlob = []byte("my secret")
+	if err := cred.Write(); err == nil {
+		fmt.Println("Created")
+	}
+}