From 316c3e73a195e9fbf4785834afa9fab87031c3d7 Mon Sep 17 00:00:00 2001 From: Chris Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com> Date: Wed, 15 Apr 2026 21:20:23 -0400 Subject: [PATCH 1/3] Fix DocFX configuration and add documentation content The docs site was blank because docfx_project/ still contained repo-template placeholders. Replace all placeholders with real values and write actual documentation content. - docfx.json: fix project path, app name, title, base URL, templates - Add root toc.yml linking Documentation and API Reference sections - Add logo.svg (branded W mark) - Write landing page (index.md) with quick links and install snippet - Write introduction.md covering Try, Result, Result, and composition - Write getting-started.md with installation and usage examples - Fix docs/toc.yml: correct project URL (was DbContextBuilder) - Add api/index.md for API reference landing page - Add .gitignore for api/ (generated yml) and _site/ (build output) Co-Authored-By: Claude Opus 4.6 (1M context) --- docfx_project/_site/.gitignore | 3 + docfx_project/api/.gitignore | 3 + docfx_project/api/index.md | 11 ++ docfx_project/docfx.json | 39 +++---- docfx_project/docs/getting-started.md | 144 +++++++++++++++++++++++++- docfx_project/docs/index.md | 8 ++ docfx_project/docs/introduction.md | 80 +++++++++++++- docfx_project/docs/toc.yml | 4 +- docfx_project/index.md | 40 ++++++- docfx_project/logo.svg | 23 ++++ docfx_project/toc.yml | 5 + 11 files changed, 334 insertions(+), 26 deletions(-) create mode 100644 docfx_project/_site/.gitignore create mode 100644 docfx_project/api/.gitignore create mode 100644 docfx_project/api/index.md create mode 100644 docfx_project/docs/index.md create mode 100644 docfx_project/logo.svg create mode 100644 docfx_project/toc.yml diff --git a/docfx_project/_site/.gitignore b/docfx_project/_site/.gitignore new file mode 100644 index 0000000..1c0a356 --- /dev/null +++ b/docfx_project/_site/.gitignore @@ -0,0 +1,3 @@ +# DocFX build output — generated by `docfx build` +* +!.gitignore diff --git a/docfx_project/api/.gitignore b/docfx_project/api/.gitignore new file mode 100644 index 0000000..4a41861 --- /dev/null +++ b/docfx_project/api/.gitignore @@ -0,0 +1,3 @@ +# DocFX auto-generated metadata files — rebuilt by `docfx metadata` +*.yml +!.gitignore diff --git a/docfx_project/api/index.md b/docfx_project/api/index.md new file mode 100644 index 0000000..62785a8 --- /dev/null +++ b/docfx_project/api/index.md @@ -0,0 +1,11 @@ +# API Reference + +Welcome to the Wolfgang.TryPattern API documentation. + +This section contains the complete API reference, automatically generated from XML documentation comments in the source code. + +Browse the navigation menu to explore available namespaces and types. + +## Getting Started + +For usage examples and guides, see the [Documentation](../docs/getting-started.md) section. diff --git a/docfx_project/docfx.json b/docfx_project/docfx.json index 0bcc566..1dd8754 100644 --- a/docfx_project/docfx.json +++ b/docfx_project/docfx.json @@ -4,42 +4,43 @@ { "src": [ { - "files": [ - "src//.csproj" - ], + "files": ["src/**/*.csproj"], "src": "../" } ], - "dest": "api" + "dest": "api", + "properties": { + "TargetFramework": "net8.0" + }, + "disableGitFeatures": false, + "disableDefaultFilter": false } ], "build": { "content": [ { - "files": [ - "**/*.{md,yml}" - ], - "exclude": [ - "_site/**" - ] + "files": ["**/*.{md,yml}"], + "exclude": ["_site/**"] } ], "resource": [ { - "files": [ - "images/**" - ] + "files": ["logo.svg", "images/**"] } ], "output": "_site", - "template": [ - "modern", - "default" - ], + "template": ["default", "modern"], "globalMetadata": { - "_appName": "", - "_appTitle": "", + "_appName": "Wolfgang.TryPattern", + "_appTitle": "Wolfgang.TryPattern Documentation", + "_appLogoPath": "logo.svg", "_enableSearch": true, + "_appFooter": "Made with DocFX", + "_disableSidebar": false, + "_disableTocFilter": false, + "_enableDarkMode": true, + "colorMode": "dark", + "_baseUrl": "https://Chris-Wolfgang.github.io/Try-Pattern/", "pdf": true } } diff --git a/docfx_project/docs/getting-started.md b/docfx_project/docs/getting-started.md index 8b3a794..1bd2713 100644 --- a/docfx_project/docs/getting-started.md +++ b/docfx_project/docs/getting-started.md @@ -1 +1,143 @@ -# Getting Started \ No newline at end of file +# Getting Started + +## Prerequisites + +- .NET SDK 8.0 or later (for development) +- Any project targeting .NET Framework 4.6.2+, .NET Standard 2.0, .NET 8.0, or .NET 10.0 + +## Installation + +### Package Manager Console + +```powershell +Install-Package Wolfgang.TryPattern +``` + +### .NET CLI + +```bash +dotnet add package Wolfgang.TryPattern +``` + +### PackageReference + +```xml +<PackageReference Include="Wolfgang.TryPattern" Version="0.2.0" /> +``` + +## Basic Usage + +### Running an Action + +Use `Try.Run` to execute an action that might throw: + +```csharp +using Wolfgang.TryPattern; + +var result = Try.Run(() => File.Delete(tempPath)); + +if (result.Failed) +{ + Console.WriteLine($"Could not delete file: {result.ErrorMessage}"); +} +``` + +### Running a Function + +Use `Try.Run<T>` to execute a function and capture its return value: + +```csharp +var result = Try.Run(() => int.Parse(userInput)); + +if (result.Succeeded) +{ + Console.WriteLine($"Parsed value: {result.Value}"); +} +else +{ + Console.WriteLine($"Invalid input: {result.ErrorMessage}"); +} +``` + +### Async Operations + +Both `Action` and `Func<Task<T>>` have async counterparts: + +```csharp +var result = await Try.RunAsync( + () => httpClient.GetStringAsync(url) +); + +if (result.Succeeded) +{ + ProcessResponse(result.Value); +} +``` + +Async operations support cancellation: + +```csharp +var result = await Try.RunAsync( + () => httpClient.GetStringAsync(url), + cancellationToken +); +``` + +> [!NOTE] +> `OperationCanceledException` is intentionally **not** caught by `Try.RunAsync`. Cancellation propagates normally so callers can distinguish between a failed operation and a cancelled one. + +### Composing Results + +When you need to run multiple operations and check the overall outcome: + +```csharp +var result1 = Try.Run(() => ValidateName(name)); +var result2 = Try.Run(() => ValidateEmail(email)); +var result3 = Try.Run(() => ValidateAge(age)); + +// Check if any failed +if (Result.AnyFailed(result1, result2, result3)) +{ + Console.WriteLine("Validation errors occurred."); +} + +// Or flatten into a single result with combined error messages +var combined = Result.Flatten(result1, result2, result3); + +if (combined.Failed) +{ + // ErrorMessage contains all failure messages joined by newlines + Console.WriteLine(combined.ErrorMessage); +} +``` + +### Creating Results Directly + +You can also create `Result` objects directly for your own methods: + +```csharp +public Result ValidateOrder(Order order) +{ + if (order.Items.Count == 0) + { + return Result.Failure("Order must contain at least one item."); + } + + return Result.Success(); +} + +public Result<decimal> CalculateDiscount(Order order) +{ + if (order.Total < 50) + { + return Result<decimal>.Failure("Minimum order for discount is $50."); + } + + return Result<decimal>.Success(order.Total * 0.10m); +} +``` + +## Next Steps + +- Browse the [API Reference](../api/Wolfgang.TryPattern.yml) for complete method signatures and XML documentation +- View the [source code](https://github.com/Chris-Wolfgang/Try-Pattern) on GitHub diff --git a/docfx_project/docs/index.md b/docfx_project/docs/index.md new file mode 100644 index 0000000..0111b86 --- /dev/null +++ b/docfx_project/docs/index.md @@ -0,0 +1,8 @@ +# Wolfgang.TryPattern Documentation + +Welcome to the documentation section. Browse the topics in the navigation menu to get started. + +## Available Documentation + +- [Introduction](introduction.md) - Overview and introduction +- [Getting Started](getting-started.md) - Quick start guide diff --git a/docfx_project/docs/introduction.md b/docfx_project/docs/introduction.md index f6ecaa6..f9e7dbd 100644 --- a/docfx_project/docs/introduction.md +++ b/docfx_project/docs/introduction.md @@ -1 +1,79 @@ -# Introduction \ No newline at end of file +# Introduction + +Wolfgang.TryPattern is a lightweight .NET library that brings structured error handling to your codebase through the Try pattern. It replaces scattered try/catch blocks with a clean, composable API that makes error handling explicit and predictable. + +## The Problem + +Traditional .NET error handling relies on try/catch blocks that can obscure control flow, make it difficult to compose operations, and lead to inconsistent error handling across a codebase: + +```csharp +string content; +try +{ + content = File.ReadAllText(path); +} +catch (Exception ex) +{ + // Now what? Log? Return null? Throw a different exception? + logger.LogError(ex, "Failed to read file"); + return null; +} +``` + +## The Solution + +Wolfgang.TryPattern wraps operations in `Try.Run` and returns a `Result` object that clearly communicates the outcome: + +```csharp +var result = Try.Run(() => File.ReadAllText(path)); + +if (result.Succeeded) +{ + Console.WriteLine(result.Value); +} +else +{ + Console.WriteLine($"Error: {result.ErrorMessage}"); +} +``` + +## Core Types + +### `Try` + +A static class providing methods to execute actions and functions with automatic exception handling: + +- **`Try.Run(Action)`** - Execute an action, returning a `Result` +- **`Try.Run<T>(Func<T>)`** - Execute a function, returning a `Result<T>` with the return value +- **`Try.RunAsync(Action, CancellationToken)`** - Execute an action asynchronously +- **`Try.RunAsync<T>(Func<Task<T>>, CancellationToken)`** - Execute an async function + +### `Result` + +Represents the outcome of an operation: + +- **`Succeeded`** - `true` if the operation completed without exceptions +- **`Failed`** - `true` if the operation threw an exception +- **`ErrorMessage`** - The exception message if the operation failed + +### `Result<T>` + +Extends `Result` with a typed return value: + +- **`Value`** - The return value from the function (throws `InvalidOperationException` if accessed on a failed result) + +### Composition Helpers + +- **`Result.Flatten(params Result[])`** - Combine multiple results into one; if any failed, the error messages are joined +- **`Result.AnyFailed(params Result[])`** - Check if any result in a set indicates failure +- **`Result.AllSucceeded(params Result[])`** - Check if every result in a set indicates success + +## Platform Support + +Wolfgang.TryPattern targets multiple frameworks for broad compatibility: + +| Target | Version | +|--------|---------| +| .NET Framework | 4.6.2+ | +| .NET Standard | 2.0 | +| .NET | 8.0, 10.0 | diff --git a/docfx_project/docs/toc.yml b/docfx_project/docs/toc.yml index 669b07d..28b3ab4 100644 --- a/docfx_project/docs/toc.yml +++ b/docfx_project/docs/toc.yml @@ -1,8 +1,8 @@ - name: Index - href: Index.md + href: index.md - name: Introduction href: introduction.md - name: Getting Started href: getting-started.md - name: Project website - href: https://github.com/Chris-Wolfgang/DbContextBuilder + href: 'https://github.com/Chris-Wolfgang/Try-Pattern' diff --git a/docfx_project/index.md b/docfx_project/index.md index 9bc17e9..231a076 100644 --- a/docfx_project/index.md +++ b/docfx_project/index.md @@ -2,8 +2,42 @@ _layout: landing --- -# Title +# Wolfgang.TryPattern Documentation -## Quick Start Notes: +Welcome to the Wolfgang.TryPattern documentation. This site contains comprehensive guides, API reference, and examples to help you get started. -<!--1. Add images to the *images* folder if the file is referencing an image.--> +## Quick Links + +- [Getting Started](docs/getting-started.md) - Installation and basic usage +- [API Reference](api/Wolfgang.TryPattern.yml) - Complete API documentation +- [GitHub Repository](https://github.com/Chris-Wolfgang/Try-Pattern) - View source code + +## About Wolfgang.TryPattern + +Wolfgang.TryPattern is a lightweight .NET library that provides structured error handling through the Try pattern. Instead of scattering try/catch blocks throughout your code, wrap operations in `Try.Run` and get back a `Result` that clearly indicates success or failure. + +## Installation + +```bash +dotnet add package Wolfgang.TryPattern +``` + +## Documentation Sections + +### [Documentation](docs/getting-started.md) + +Step-by-step guides and tutorials to help you use Wolfgang.TryPattern effectively. + +### [API Reference](api/Wolfgang.TryPattern.yml) + +Complete API documentation automatically generated from source code XML comments. + +## Additional Resources + +- [Contributing Guidelines](https://github.com/Chris-Wolfgang/Try-Pattern/blob/main/CONTRIBUTING.md) +- [Code of Conduct](https://github.com/Chris-Wolfgang/Try-Pattern/blob/main/CODE_OF_CONDUCT.md) +- [License](https://github.com/Chris-Wolfgang/Try-Pattern/blob/main/LICENSE) + +--- + +*Documentation built with [DocFX](https://dotnet.github.io/docfx/)* diff --git a/docfx_project/logo.svg b/docfx_project/logo.svg new file mode 100644 index 0000000..8de55ae --- /dev/null +++ b/docfx_project/logo.svg @@ -0,0 +1,23 @@ +<svg width="48" height="48" viewBox="0 0 48 48" + xmlns="http://www.w3.org/2000/svg"> + <defs> + <!-- Soft purple glow for dark backgrounds --> + <filter id="glow" x="-40%" y="-40%" width="180%" height="180%"> + <feDropShadow dx="0" dy="0" stdDeviation="2" flood-color="#7c23bb" flood-opacity="0.5"/> + </filter> + </defs> + <style> + @font-face { + font-family: 'DM Serif Display'; + src: url('https://fonts.gstatic.com/s/dmserifdisplay/v13/-nF6OG414u0gLgBvIEjRpMqB6mM.woff2') format('woff2'); + } + .fancy { + font-family: 'DM Serif Display', serif; + font-size: 34px; + fill: #7c23bb; + letter-spacing: 1px; + filter: url(#glow); + } + </style> + <text x="7" y="37" class="fancy">W</text> +</svg> \ No newline at end of file diff --git a/docfx_project/toc.yml b/docfx_project/toc.yml new file mode 100644 index 0000000..8e62d99 --- /dev/null +++ b/docfx_project/toc.yml @@ -0,0 +1,5 @@ +- name: Documentation + href: docs/toc.yml +- name: API Reference + href: api/toc.yml + homepage: api/index.md From a59277017a399866790665f637eae6e219c8433c Mon Sep 17 00:00:00 2001 From: Chris Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com> Date: Wed, 15 Apr 2026 21:41:05 -0400 Subject: [PATCH 2/3] Address Copilot review: fix API links, base URL, and prerequisites - Remove _baseUrl from docfx.json (conflicts with versioned deployment under /versions/<tag>/) - Change API links from .yml to api/index.md (yml files aren't served) - Update prerequisites to .NET 10 SDK (repo multi-targets net10.0) Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com> --- docfx_project/docfx.json | 1 - docfx_project/docs/getting-started.md | 4 ++-- docfx_project/index.md | 4 ++-- 3 files changed, 4 insertions(+), 5 deletions(-) diff --git a/docfx_project/docfx.json b/docfx_project/docfx.json index 1dd8754..e8966d4 100644 --- a/docfx_project/docfx.json +++ b/docfx_project/docfx.json @@ -40,7 +40,6 @@ "_disableTocFilter": false, "_enableDarkMode": true, "colorMode": "dark", - "_baseUrl": "https://Chris-Wolfgang.github.io/Try-Pattern/", "pdf": true } } diff --git a/docfx_project/docs/getting-started.md b/docfx_project/docs/getting-started.md index 1bd2713..045d5b1 100644 --- a/docfx_project/docs/getting-started.md +++ b/docfx_project/docs/getting-started.md @@ -2,7 +2,7 @@ ## Prerequisites -- .NET SDK 8.0 or later (for development) +- .NET 10 SDK or later (required to build and test this repository, because the library multi-targets .NET 10.0) - Any project targeting .NET Framework 4.6.2+, .NET Standard 2.0, .NET 8.0, or .NET 10.0 ## Installation @@ -139,5 +139,5 @@ public Result<decimal> CalculateDiscount(Order order) ## Next Steps -- Browse the [API Reference](../api/Wolfgang.TryPattern.yml) for complete method signatures and XML documentation +- Browse the [API Reference](../api/index.md) for complete method signatures and XML documentation - View the [source code](https://github.com/Chris-Wolfgang/Try-Pattern) on GitHub diff --git a/docfx_project/index.md b/docfx_project/index.md index 231a076..f032844 100644 --- a/docfx_project/index.md +++ b/docfx_project/index.md @@ -9,7 +9,7 @@ Welcome to the Wolfgang.TryPattern documentation. This site contains comprehensi ## Quick Links - [Getting Started](docs/getting-started.md) - Installation and basic usage -- [API Reference](api/Wolfgang.TryPattern.yml) - Complete API documentation +- [API Reference](api/index.md) - Complete API documentation - [GitHub Repository](https://github.com/Chris-Wolfgang/Try-Pattern) - View source code ## About Wolfgang.TryPattern @@ -28,7 +28,7 @@ dotnet add package Wolfgang.TryPattern Step-by-step guides and tutorials to help you use Wolfgang.TryPattern effectively. -### [API Reference](api/Wolfgang.TryPattern.yml) +### [API Reference](api/index.md) Complete API documentation automatically generated from source code XML comments. From 9d8e391e1af9f84816f58ca4bfb9312a619850ea Mon Sep 17 00:00:00 2001 From: Chris Wolfgang <210299580+Chris-Wolfgang@users.noreply.github.com> Date: Wed, 15 Apr 2026 21:49:39 -0400 Subject: [PATCH 3/3] Trigger CI