Skip to content

Example: library overview

overview.md is the entry point for a single library's documentation set. Doc gen produces one per library folder under docs/libraries/<slug>/, describing what the library does and pointing at every other page in the set.

What reviewers should check

  • The ## Purpose section uses prose or bullets only. A Field/Value table there is a defect — assembly metadata belongs in the documentation context block at the top of the page, not in Purpose.
  • The documentation context block appears immediately under the H1 as a blockquote, and its context label matches how the library was reached (frontend-referenced or nuspec-referenced).
  • ## Related documentation lists every standard page except overview.md itself, and conditional pages appear only when that file really exists in the library folder.
  • Related documentation link text uses the canonical document names exactly — Index, Architecture, Dependencies, API reference — never the library name or an invented label.
  • The library frontmatter value is the dotted assembly name (SAIF.Framework.Validation), not the folder slug, and reference_type is either package or embedded.
  • ## Sources is the final section and lists real repo-relative paths, including the project file.

Example

The document below is a complete, correct overview.md for a fictional library.

View rendered example — the same document as a real page, so you can compare rendering as well as source.

---
title: SAIF.Framework.Validation overview
summary: High-level purpose, scope, and responsibilities for this library.
status: draft
owner: Policy Systems Team
last_reviewed: 2026-02-18
library: SAIF.Framework.Validation
reference_type: package
---

# SAIF.Framework.Validation overview

> **Documentation context:** Nuspec-referenced package library
>
> A separate documentation set exists for this library as a
> frontend-referenced library.

SAIF.Framework.Validation is a .NET Framework 4.8 class library that applies
declarative validation rules to workers' compensation policy and claims data
before it is persisted. Rule definitions are loaded from XML rule sets at
startup and evaluated against caller-supplied records, so consuming
applications enforce the same field- and record-level checks without
duplicating validation logic. The library is distributed as the
`SAIF.Framework.Validation` NuGet package and consumed by both interactive and
batch applications.

## Purpose
- Evaluates field-level and record-level validation rules against policy and
  claims data, returning a structured result that identifies every failure
  rather than stopping at the first one.
- Consumed by `SAIF.Claims.Intake` to validate operator entry before submission
  and by `SAIF.PremiumAudit.Batch` to reject malformed audit records during
  overnight processing.

## Responsibilities
- Loads and caches named rule sets from XML definition files at first use.
- Executes rules in declaration order against a supplied record, collecting all
  failures into a single `ValidationResult`.
- Resolves policy effective dates and claim jurisdiction from the calling
  application through `IValidationContext` so rules can vary by state.
- Distinguishes hard failures, which block persistence, from warnings, which
  the caller may accept.
- Reports rule identifiers on every failure so consuming applications can map a
  message back to a documented business rule.

## Key components
- `ValidationEngine`: Coordinates rule execution for a record and aggregates
  failures into a `ValidationResult`.
- `ValidationRule`: Represents a single evaluable rule, including its severity,
  target field, and business rule identifier.
- `ValidationResult`: Carries the pass/fail outcome plus the ordered collection
  of failures and warnings produced by a run.
- `RuleSetLoader`: Reads XML rule set files, materializes `ValidationRule`
  instances, and caches them by rule set name.
- `IValidationContext`: Supplies jurisdiction, effective date, and user
  identity from the consuming application to rules that need them.

## Related documentation
- [Index](index.md)
- [Architecture](architecture.md)
- [Dependencies](dependencies.md)
- [Configuration](configuration.md)
- [Operations and processes](operations-processes.md)
- [Business rules](business-rules.md)
- [API reference](api/index.md)

## Sources
- src/SAIF.Framework.Validation/SAIF.Framework.Validation.vbproj
- src/SAIF.Framework.Validation/ValidationEngine.vb
- src/SAIF.Framework.Validation/Rules/ValidationRule.vb
- src/SAIF.Framework.Validation/RuleSetLoader.vb
- src/SAIF.Framework.Validation/SAIF.Framework.Validation.nuspec