docs: update README with detailed usage instructions and API reference

README.md

@@ -1,14 +1,103 @@
-# Go TLS Library
+# Go TLS Certificate Helper
 
 [![Build Status](https://drone.yoorie.de/api/badges/go-lib/certs/status.svg)](https://drone.yoorie.de/go-lib/certs)
 
-## Documentation
+Small helper library to generate a self-signed TLS certificate and return it
+as a ready-to-use `*tls.Config`.
 
-Available project documentation:
+## Overview
+
+The package builds an in-memory certificate and private key pair from a
+`GenerateCertificate` configuration and returns a TLS configuration with one
+certificate entry.
+
+Supported key options:
+
+- RSA (default when `EcdsaCurve` is empty and `Ed25519Key` is false)
+- Ed25519 (when `Ed25519Key` is true)
+- ECDSA curves: `P224`, `P256`, `P384`, `P521`
+
+## Installation
+
+```bash
+go get scm.yoorie.de/go-lib/certs
+```
+
+## Quick Start
+
+```go
+package main
+
+import (
+    "fmt"
+    "time"
+
+    "scm.yoorie.de/go-lib/certs"
+)
+
+func main() {
+    cfg := &certs.GenerateCertificate{
+        Organization: "example.org",
+        Host:         "127.0.0.1,localhost,api.example.org",
+        ValidFor:     365 * 24 * time.Hour,
+        RSABits:      2048,
+    }
+
+    tlsConfig, err := cfg.GenerateTLSConfig()
+    if err != nil {
+        panic(err)
+    }
+
+    fmt.Printf("certificates in config: %d\n", len(tlsConfig.Certificates))
+}
+```
+
+## API
+
+### Type: `GenerateCertificate`
+
+- `Organization string`: certificate subject organization
+- `Host string`: comma-separated DNS names and/or IPs for SAN
+- `ValidFrom string`: optional start date in format `Jan 2 15:04:05 2006`
+- `ValidFor time.Duration`: certificate validity duration
+- `IsCA bool`: whether to mark certificate as CA
+- `RSABits int`: RSA key size when RSA is used
+- `EcdsaCurve string`: one of `P224`, `P256`, `P384`, `P521`
+- `Ed25519Key bool`: generate Ed25519 key when true
+
+### Method
+
+- `GenerateTLSConfig() (*tls.Config, error)`
+
+Creates a self-signed certificate and returns a `*tls.Config` with that
+certificate.
+
+## Important Notes
+
+- The certificate is self-signed (issuer equals subject).
+- `Host` is split by comma and mapped into DNS or IP SAN entries.
+- Invalid `EcdsaCurve` values are not recoverable: the implementation uses
+  `log.Fatalf`.
+- Invalid `ValidFrom` values are not recoverable: the implementation uses
+  `log.Fatalf`.
+
+## Development
+
+Run quality checks locally:
+
+```bash
+go test ./...
+go test -coverprofile .build/coverage.out ./...
+go tool cover -func .build/coverage.out
+go vet ./...
+go run golang.org/x/vuln/cmd/govulncheck@latest ./...
+```
+
+## Documentation
 
 - [Changelog](CHANGELOG.md)
 - [Definition of Done](docs/DEFINITION_OF_DONE.md)
 - [Releasing](docs/RELEASING.md)
 
 ---
-Copyright © 2023 yoorie.de
+Copyright © 2026 yoorie.de