Document exported fields (#13)

* add doc for exported fields

* update

* update

* update comments

* update example

* add package comment

Author: linglingye001

azureappconfiguration.go

@@ -1,6 +1,15 @@
 // Copyright (c) Microsoft Corporation.
 // Licensed under the MIT License.
 
+// Package azureappconfiguration provides a client for Azure App Configuration, enabling Go applications
+// to manage application settings with Microsoft's Azure App Configuration service.
+//
+// The azureappconfiguration package allows loading configuration data from Azure App Configuration in a structured way,
+// with support for automatic Key Vault reference resolution, hierarchical configuration construction,
+// and strongly typed configuration binding.
+//
+// For more information about Azure App Configuration, see:
+// https://learn.microsoft.com/en-us/azure/azure-app-configuration/
 package azureappconfiguration
 
 import (
@@ -17,6 +26,7 @@ import (
 	"golang.org/x/sync/errgroup"
 )
 
+// An AzureAppConfiguration is a configuration provider that stores and manages settings sourced from Azure App Configuration.
 type AzureAppConfiguration struct {
 	keyValues    map[string]any
 	kvSelectors  []Selector
@@ -26,6 +36,17 @@ type AzureAppConfiguration struct {
 	resolver      *keyVaultReferenceResolver
 }
 
+// Load initializes a new AzureAppConfiguration instance and loads the configuration data from
+// Azure App Configuration service.
+//
+// Parameters:
+// - ctx: The context for the operation.
+// - authentication: Authentication options for connecting to the Azure App Configuration service
+// - options: Configuration options to customize behavior, such as key filters and prefix trimming
+//
+// Returns:
+// - A configured AzureAppConfiguration instance that provides access to the loaded configuration data
+// - An error if the operation fails, such as authentication errors or connectivity issues
 func Load(ctx context.Context, authentication AuthenticationOptions, options *Options) (*AzureAppConfiguration, error) {
 	if err := verifyAuthenticationOptions(authentication); err != nil {
 		return nil, err
@@ -58,6 +79,18 @@ func Load(ctx context.Context, authentication AuthenticationOptions, options *Op
 	return azappcfg, nil
 }
 
+// Unmarshal parses the configuration and stores the result in the value pointed to v. It builds a hierarchical configuration structure based on key separators. 
+// It supports converting values to appropriate target types.
+//
+// Fields in the target struct are matched with configuration keys using the field name by default.
+// For custom field mapping, use json struct tags.
+//
+// Parameters:
+// - v: A pointer to the struct to populate with configuration values
+// - options: Optional parameters (e,g, separator) for controlling the unmarshalling behavior
+//
+// Returns:
+// - An error if unmarshalling fails due to type conversion issues or invalid configuration
 func (azappcfg *AzureAppConfiguration) Unmarshal(v any, options *ConstructionOptions) error {
 	if options == nil || options.Separator == "" {
 		options = &ConstructionOptions{
@@ -88,6 +121,15 @@ func (azappcfg *AzureAppConfiguration) Unmarshal(v any, options *ConstructionOpt
 	return decoder.Decode(azappcfg.constructHierarchicalMap(options.Separator))
 }
 
+// GetBytes returns the configuration as a JSON byte array with hierarchical structure. 
+// This method is particularly useful for integrating with "encoding/json" package or third-party configuration packages like Viper or Koanf.
+//
+// Parameters:
+// - options: Optional parameters for controlling JSON construction, particularly the key separator
+//
+// Returns:
+// - A byte array containing the JSON representation of the configuration
+// - An error if JSON marshalling fails or if an invalid separator is specified
 func (azappcfg *AzureAppConfiguration) GetBytes(options *ConstructionOptions) ([]byte, error) {
 	if options == nil || options.Separator == "" {
 		options = &ConstructionOptions{

example_test.go

@@ -0,0 +1,106 @@
+//go:build examples
+// +build examples
+
+// Copyright (c) Microsoft Corporation.
+// Licensed under the MIT License.
+
+package azureappconfiguration_test
+
+import (
+	"context"
+	"fmt"
+	"log"
+	"os"
+
+	"github.com/Azure/AppConfiguration-GoProvider/azureappconfiguration"
+)
+
+func ExampleLoad() {
+	// Get the endpoint from environment variable
+	endpoint := os.Getenv("AZURE_APPCONFIG_ENDPOINT")
+	if endpoint == "" {
+		log.Fatal("AZURE_APPCONFIG_ENDPOINT environment variable not set")
+	}
+
+	// Create a credential using DefaultAzureCredential
+	credential, err := azidentity.NewDefaultAzureCredential(nil)
+	if err != nil {
+		log.Fatalf("Failed to create credential: %v", err)
+	}
+
+	// Set up authentication options with endpoint and credential
+	authOptions := azureappconfiguration.AuthenticationOptions{
+		Endpoint:   endpoint,
+		Credential: credential,
+	}
+
+	// Create a context
+	ctx := context.Background()
+
+	// Load configuration with default options
+	provider, err := azureappconfiguration.Load(ctx, authOptions, nil)
+	if err != nil {
+		log.Fatalf("Failed to load configuration: %v", err)
+	}
+
+	// Use the provider...
+	fmt.Printf("Configuration loaded successfully: %v\n", provider != nil)
+
+	// Output:
+	// Configuration loaded successfully: true
+}
+
+func ExampleAzureAppConfiguration_Unmarshal() {
+	// Assume we have already loaded the provider
+	provider, _ := loadExampleProvider()
+
+	// Define a configuration structure
+	type ServerConfig struct {
+		Port    int      `json:"port"`
+		Host    string   `json:"host"`
+		Debug   bool     `json:"debug"`
+		Timeout int      `json:"timeout"`
+		Tags    []string `json:"tags"`
+	}
+
+	// Unmarshal into the struct
+	var config ServerConfig
+	err := provider.Unmarshal(&config, nil)
+	if err != nil {
+		log.Fatalf("Failed to unmarshal configuration: %v", err)
+	}
+
+	fmt.Printf("Server will run at %s:%d\n", config.Host, config.Port)
+	fmt.Printf("Debug mode: %v, Timeout: %d seconds\n", config.Debug, config.Timeout)
+	fmt.Printf("Tags: %v\n", config.Tags)
+
+	// Output:
+	// Server will run at localhost:8080
+	// Debug mode: true, Timeout: 30 seconds
+	// Tags: [production primary]
+}
+
+func ExampleAzureAppConfiguration_GetBytes() {
+	// Assume we have already loaded the provider
+	provider, _ := loadExampleProvider()
+
+	// Get configuration as JSON bytes
+	jsonBytes, err := provider.GetBytes(&azureappconfiguration.ConstructionOptions{
+		Separator: ":", // Use ":" as the separator in hierarchical keys
+	})
+	if err != nil {
+		log.Fatalf("Failed to get configuration as bytes: %v", err)
+	}
+
+	// Print the JSON string for demonstration
+	fmt.Println(string(jsonBytes))
+
+	// Output would be JSON like:
+	// {"database":{"host":"localhost","port":5432,"username":"admin"},"debug":true,"timeout":30}
+}
+
+// Helper function to simulate loading a provider for examples
+func loadExampleProvider() (*azureappconfiguration.AzureAppConfiguration, error) {
+	// Since we can't actually connect in an example, this is just a placeholder
+	return nil, nil // In real examples, this would return a valid provider
+}

options.go

@@ -12,48 +12,83 @@ import (
 )
 
 // Options contains optional parameters to configure the behavior of an Azure App Configuration provider.
-// If selectors are not provided, all key-values with no label are loaded.
+// It provides control over which key-values to fetch, how to trim key prefixes, and how to handle Key Vault references.
 type Options struct {
-	// Trims the provided prefixes from the keys of all key-values retrieved from Azure App Configuration.
+	// TrimKeyPrefixes specifies a list of prefixes to trim from the keys of all key-values
+	// retrieved from Azure App Configuration, making them more suitable for binding to structured types.
 	TrimKeyPrefixes []string
+
+	// Selectors defines what key-values to load from Azure App Configuration
+	// Each selector combines a key filter and label filter
+	// If selectors are not provided, all key-values with no label are loaded by default.
 	Selectors       []Selector
+
+	// KeyVaultOptions configures how Key Vault references are resolved.
 	KeyVaultOptions KeyVaultOptions
+
+	// ClientOptions provides options for configuring the underlying Azure App Configuration client.
 	ClientOptions   *azappconfig.ClientOptions
 }
 
-// AuthenticationOptions contains optional parameters to construct an Azure App Configuration client
-// ConnectionString or endpoint with credential must be be provided
+// AuthenticationOptions contains parameters for authenticating with the Azure App Configuration service.
+// Either a connection string or an endpoint with credential must be provided.
 type AuthenticationOptions struct {
+	// Credential is a token credential for Azure EntraID Authenticaiton.
+	// Required when Endpoint is provided.
 	Credential       azcore.TokenCredential
+
+	// Endpoint is the URL of the Azure App Configuration service.
+	// Required when using token-based authentication with Credential.
 	Endpoint         string
+
+	// ConnectionString is the connection string for the Azure App Configuration service.
 	ConnectionString string
 }
 
-// Selector specifies what key-values to include in the configuration provider.
+// Selector specifies what key-values to load from Azure App Configuration.
 type Selector struct {
+	// KeyFilter specifies which keys to retrieve from Azure App Configuration.
+	// It can include wildcards, e.g. "app*" will match all keys starting with "app".
 	KeyFilter   string
+
+	// LabelFilter specifies which labels to retrieve from Azure App Configuration.
+	// Empty string or omitted value will use the default no-label filter.
+	// Note: Wildcards are not supported in label filters.
 	LabelFilter string
 }
 
-// SecretResolver is an interface to resolve secret from key vault reference
+// SecretResolver is an interface to resolve secrets from Key Vault references.
+// Implement this interface to provide custom secret resolution logic.
 type SecretResolver interface {
-	// keyVaultReference: "https://{keyVaultName}.vault.azure.net/secrets/{secretName}/{secretVersion}"
+	// ResolveSecret resolves a Key Vault reference URL to the actual secret value.
+	//
+	// Parameters:
+	// - ctx: The context for the operation
+	// - keyVaultReference: A URL in the format "https://{keyVaultName}.vault.azure.net/secrets/{secretName}/{secretVersion}"
+	//
+	// Returns:
+	// - The resolved secret value as a string
+	// - An error if the secret could not be resolved
 	ResolveSecret(ctx context.Context, keyVaultReference url.URL) (string, error)
 }
 
-// KeyVaultOptions contains optional parameters to configure the behavior of key vault reference resolution
+// KeyVaultOptions contains parameters to configure the build-in Key Vault reference resolution.
+// These options determine how the provider will authenticate with and retrieve
 type KeyVaultOptions struct {
-	// Credential specifies the token credential used to authenticate to key vaults
+	// Credential specifies the token credential used to authenticate to Azure Key Vault services.
+	// This is required for Key Vault reference resolution unless a custom SecretResolver is provided.
 	Credential azcore.TokenCredential
 
-	// SecretResolver specifies the callback used to resolve key vault references
+	// SecretResolver specifies a custom implementation for resolving Key Vault references.
+	// When provided, this takes precedence over using the default resolver with Credential.
 	SecretResolver SecretResolver
 }
 
-// ConstructionOptions contains optional parameters for Unmarshal and GetBytes methods
+// ConstructionOptions contains parameters for parsing keys with hierarchical structure.
 type ConstructionOptions struct {
-	// Separator is used to unmarshal configuration when the keys themselves contain the separator
+	// Separator specifies the character used to determine hierarchy in configuration keys
+	// when mapping to nested struct fields during unmarshaling operations.
 	// Supported values: '.', ',', ';', '-', '_', '__', '/', ':'.
-	// If not provided, the default separator "." will be used
+	// If not provided, the default separator "." will be used.
 	Separator string
 }