Tweaked namespace docs

bastianeicher · bastianeicher · commit da1972e5f331 · 2026-01-02T14:18:30.000+01:00
diff --git a/doc/index.md b/doc/index.md
@@ -11,11 +11,11 @@ This website documents the [API](xref:NanoByte.Common) of the NanoByte.Common Nu
 - integration with [native Windows and Linux features](xref:NanoByte.Common.Native),
 - [network](xref:NanoByte.Common.Net) and [disk](xref:NanoByte.Common.Storage) IO,
 - [advanced collections](xref:NanoByte.Common.Collections) and
-- [undo/redo logic](undo.md).
+- [undo/redo logic](xref:NanoByte.Common.Undo).
 
 **[NanoByte.Common.AnsiCli](https://www.nuget.org/packages/NanoByte.Common.AnsiCli/)** adds ANSI console output. Powered by [Spectre.Console](https://github.com/spectresystems/spectre.console).
 
 **[NanoByte.Common.WinForms](https://www.nuget.org/packages/NanoByte.Common.WinForms/)** adds various Windows Forms controls with an emphasis on:
 
-- [progress reporting](tasks.md) and
+- [progress reporting](xref:NanoByte.Common.Tasks) and
 - [data binding](xref:NanoByte.Common.Controls).
diff --git a/doc/tasks.md b/doc/tasks.md
diff --git a/doc/toc.yml b/doc/toc.yml
@@ -2,10 +2,6 @@
   href: index.md
 - name: API
   href: api/
-- name: Task system
-  href: tasks.md
-- name: Undo system
-  href: undo.md
 - name: Backports
   href: backports.md
 - name: GitHub
diff --git a/doc/undo.md b/doc/undo.md
diff --git a/src/Common.WinForms/Controls/_Namespace.md b/src/Common.WinForms/Controls/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Controls
-summary: *content
----
-WinForms controls and forms designed to simplify common UI designs.
+---
+uid: NanoByte.Common.Controls
+summary: WinForms controls and forms designed to simplify common UI designs.
+---
diff --git a/src/Common.WinForms/Drawing/_Namespace.md b/src/Common.WinForms/Drawing/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Drawing
-summary: *content
----
-Helpers for manipulating images
+---
+uid: NanoByte.Common.Drawing
+summary: Helpers for manipulating images
+---
diff --git a/src/Common/Collections/_Namespace.md b/src/Common/Collections/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Collections
-summary: *content
----
-Specialized collection types supplementing System.Collections.Generic.
+---
+uid: NanoByte.Common.Collections
+summary: Specialized collection types supplementing System.Collections.Generic.
+---
diff --git a/src/Common/Dispatch/_Namespace.md b/src/Common/Dispatch/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Dispatch
-summary: *content
----
-Functionality like double dispatch and two/three-way merging.
+---
+uid: NanoByte.Common.Dispatch
+summary: Functionality like double dispatch and two/three-way merging.
+---
diff --git a/src/Common/Info/_Namespace.md b/src/Common/Info/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Info
-summary: *content
----
-Data structures providing diagnostic information about the application, the operating system, etc..
+---
+uid: NanoByte.Common.Info
+summary: Data structures providing diagnostic information about the application, the operating system, etc..
+---
diff --git a/src/Common/Native/_Namespace.md b/src/Common/Native/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Native
-summary: *content
----
-Utility classes that provide OS-specific helper functions.
+---
+uid: NanoByte.Common.Native
+summary: Utility classes that provide OS-specific helper functions.
+---
diff --git a/src/Common/Net/_Namespace.md b/src/Common/Net/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Net
-summary: *content
----
-Network communication.
+---
+uid: NanoByte.Common.Net
+summary: Network communication.
+---
diff --git a/src/Common/Storage/_Namespace.md b/src/Common/Storage/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Storage
-summary: *content
----
-File system access and serialization.
+---
+uid: NanoByte.Common.Storage
+summary: File system access and serialization.
+---
diff --git a/src/Common/Streams/_Namespace.md b/src/Common/Streams/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Streams
-summary: *content
----
-Filter streams and utility classes with helper functions for stream handling.
+---
+uid: NanoByte.Common.Streams
+summary: Filter streams and utility classes with helper functions for stream handling.
+---
diff --git a/src/Common/Tasks/_Namespace.md b/src/Common/Tasks/_Namespace.md
@@ -1,5 +1,45 @@
 ---
 uid: NanoByte.Common.Tasks
-summary: *content
+summary: Task system for managing long-running tasks and reporting progress to the user.
 ---
-<xref:task-system> for managing long-running tasks and reporting progress to the user.
+## Tasks
+
+Tasks are represented using the <xref:NanoByte.Common.Tasks.ITask> interface.
+
+This library provides general-purpose implementations such as <xref:NanoByte.Common.Tasks.ActionTask> and <xref:NanoByte.Common.Tasks.ForEachTask>, as well as use-case specific ones such as <xref:NanoByte.Common.Net.DownloadFile> and <xref:NanoByte.Common.Storage.ReadFile>. You can also implement your own.
+
+## Handlers
+
+The <xref:NanoByte.Common.Tasks.ITaskHandler> interface represents a user interface for reporting task progress as well as displaying prompts and outputs to the user. This library provides a number of implementations:
+
+- <xref:NanoByte.Common.Tasks.CliTaskHandler> for a basic command-line interface
+- <xref:NanoByte.Common.Tasks.AnsiCliTaskHandler> for a more advanced command-line interface using ANSI codes
+- <xref:NanoByte.Common.Tasks.DialogTaskHandler> for a graphical interface using WinForms dialog boxes
+- <xref:NanoByte.Common.Tasks.SilentTaskHandler> for background execution or unit tests
+- `ServiceTaskHandler` for integration with [Microsoft.Extensions.DependencyInjection](https://docs.microsoft.com/dotnet/core/extensions/dependency-injection)
+
+Methods that want to run <xref:NanoByte.Common.Tasks.ITask>s should take an <xref:NanoByte.Common.Tasks.ITaskHandler> as an input parameter.  
+To run an <xref:NanoByte.Common.Tasks.ITask>, pass it to the [ITaskHandler.RunTask()](xref:NanoByte.Common.Tasks.ITaskHandler#NanoByte_Common_Tasks_ITaskHandler_RunTask_NanoByte_Common_Tasks_ITask_) method. This will then internally call [ITask.Run()](xref:NanoByte.Common.Tasks.ITask#NanoByte_Common_Tasks_ITask_Run_System_Threading_CancellationToken_NanoByte_Common_Net_ICredentialProvider_System_IProgress_NanoByte_Common_Tasks_TaskSnapshot__) and take care of setting up progress tracking, cancellation, etc.. Additional methods such as [ITaskHandler.Ask()](xref:NanoByte.Common.Tasks.ITaskHandler#NanoByte_Common_Tasks_ITaskHandler_Ask_System_String_System_Nullable_System_Boolean__System_String_) can be used for user interaction.
+
+## Threading
+
+<xref:NanoByte.Common.Tasks.ITask>s provide no threading or asynchronicity concept by themselves. Their [.Run()](xref:NanoByte.Common.Tasks.ITask#NanoByte_Common_Tasks_ITask_Run_System_Threading_CancellationToken_NanoByte_Common_Net_ICredentialProvider_System_IProgress_NanoByte_Common_Tasks_TaskSnapshot__) methods block until the tasks is complete. However, they can be cancelled from other threads via <xref:System.Threading.CancellationToken>s.
+
+<xref:NanoByte.Common.Tasks.ITaskHandler> implementations are thread-safe and support running multiple <xref:NanoByte.Common.Tasks.ITask>s concurrently.  
+[ITaskHandler.RunTask()](xref:NanoByte.Common.Tasks.ITaskHandler#NanoByte_Common_Tasks_ITaskHandler_RunTask_NanoByte_Common_Tasks_ITask_) blocks until the tasks is complete, however some implementations may perform the actual task execution on a separate thread.  
+<xref:NanoByte.Common.Tasks.DialogTaskHandler> keeps the WinForms message loop pumping while a task is running, so calling `.RunTask()` from the GUI thread will not freeze the GUI. However it does prevent user interaction (other than canceling the task) via a modal dialog box.
+
+## Comparison with async/await
+
+While <xref:NanoByte.Common.Tasks.ITask> has some superficial similarities with the <xref:System.Threading.Tasks.Task> class used by the C# `async`/`await` keywords, these two concepts should not be confused.
+
+The `async`/`await` keywords are part of the [Task Asynchronous Programming model](https://docs.microsoft.com/dotnet/csharp/programming-guide/concepts/async/task-asynchronous-programming-model) (TAP). The TAP provides an abstraction over asynchronous code, enabling the execution of continuations after tasks have completed. This is intended to increase the performance and responsiveness of applications. Many TAP methods accept <xref:System.Threading.CancellationToken>s to signal that a task should be cancelled and <xref:System.IProgress`1> to report a task's progress.
+
+NanoByte.Common's Task system is intended for managing long-running tasks. It provides an abstraction over UIs for interacting with such tasks. It uses the same <xref:System.Threading.CancellationToken> and <xref:System.IProgress`1> as the TAP, but takes care of managing them internally for most use cases.
+
+As a rule of thumb:
+
+- Use `await` and <xref:System.Threading.Tasks.Task> if you want to trigger a short task from a GUI thread.
+- Use [ITaskHandler.RunTask()](xref:NanoByte.Common.Tasks.ITaskHandler#NanoByte_Common_Tasks_ITaskHandler_RunTask_NanoByte_Common_Tasks_ITask_) and <xref:NanoByte.Common.Tasks.ITask> if you want to run a longer task on a non-GUI thread (potentially reporting back to a GUI thread).
+
+## API
diff --git a/src/Common/Threading/_Namespace.md b/src/Common/Threading/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Threading
-summary: *content
----
-Helpers for working with threads.
+---
+uid: NanoByte.Common.Threading
+summary: Helpers for working with threads.
+---
diff --git a/src/Common/Undo/_Namespace.md b/src/Common/Undo/_Namespace.md
@@ -1,5 +1,18 @@
 ---
 uid: NanoByte.Common.Undo
-summary: *content
+summary: framework for adding undo/redo functionality to your applications, based on the Command pattern.
 ---
-<xref:undo-system> based on the Command pattern.
+## Commands
+
+Commands that can be executed and also undone are represented using the <xref:NanoByte.Common.Undo.IUndoCommand> interface.
+
+This library provides a number of implementations for common use cases such as <xref:NanoByte.Common.Undo.SetValueCommand> and <xref:NanoByte.Common.Undo.AddToCollection>, but you can also implement your own.
+
+## Executors
+
+Methods that want to execute <xref:NanoByte.Common.Undo.IUndoCommand>s should take an <xref:NanoByte.Common.Undo.ICommandExecutor> as an input parameter.  
+To execute an <xref:NanoByte.Common.Undo.IUndoCommand>, pass it to the [ICommandExecutor.Execute()](xref:NanoByte.Common.Undo.ICommandExecutor#NanoByte_Common_Undo_ICommandExecutor_Execute_NanoByte_Common_Undo_IUndoCommand_) method. This will then internally call [IUndoCommand.Execute()](xref:NanoByte.Common.Undo.IUndoCommand#NanoByte_Common_Undo_IUndoCommand_Execute) and record the command for later undo operations.
+
+The class <xref:NanoByte.Common.Undo.CommandManager`1> implements the <xref:NanoByte.Common.Undo.ICommandExecutor> interface. You can expose the `.Undo()` and `.Redo()` methods of this class to your users in your GUI.
+
+## API
diff --git a/src/Common/Values/Design/_Namespace.md b/src/Common/Values/Design/_Namespace.md
@@ -1,5 +1,4 @@
 ---
 uid: NanoByte.Common.Values.Design
-summary: *content
+summary: <xref:System.ComponentModel.TypeConverter>s used for serialization and to provide a better runtime experience when using <xref:System.Windows.Forms.PropertyGrid>s.
 ---
-<xref:System.ComponentModel.TypeConverter>s used for serialization and to provide a better runtime experience when using <xref:System.Windows.Forms.PropertyGrid>s.
diff --git a/src/Common/Values/_Namespace.md b/src/Common/Values/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common.Values
-summary: *content
----
-Data structures and helpers for Value Types.
+---
+uid: NanoByte.Common.Values
+summary: Data structures and helpers for Value Types.
+---
diff --git a/src/Common/_Namespace.md b/src/Common/_Namespace.md
@@ -1,5 +1,4 @@
----
-uid: NanoByte.Common
-summary: *content
----
-Generic utility classes, interfaces, etc. that are applicable to a wide range of different applications.
+---
+uid: NanoByte.Common
+summary: Generic utility classes, interfaces, etc. that are applicable to a wide range of different applications.
+---
