Skip to content

Commit 5dd6bb8

Browse files
JusterZhuclaude
andcommitted
docs: rewrite all XML documentation in English per MS guidelines
Comprehensive rewrite of all GeneralUpdate.Core XML documentation from Chinese to English, following Microsoft official documentation conventions. Every class, interface, struct, enum, field, property, method, constructor, and delegate is now fully documented with: - <summary> describing purpose and behavior - <remarks> with step-by-step flow descriptions for core methods - <param>, <returns>, <exception> tags for all public API - <see cref> cross-references between related types - <list type=table/bullet> where appropriate Covering all 65 source files across 8 modules: Bootstrap, Strategy, Pipeline, Download, Configuration, FileSystem, Event/Differential, Network/Security/Silent. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
1 parent b14c6b7 commit 5dd6bb8

65 files changed

Lines changed: 3909 additions & 2905 deletions

File tree

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

src/c#/GeneralUpdate.Core/Bootstrap/GeneralUpdateBootstrap.cs

Lines changed: 71 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,13 @@ public GeneralUpdateBootstrap()
8787
}
8888

8989
/// <summary>Cancel the current update operation.</summary>
90+
/// <remarks>
91+
/// Signals the internal <see cref="CancellationTokenSource"/> to request cancellation
92+
/// of the ongoing update workflow. After calling this method, the running strategy
93+
/// (e.g., <see cref="Strategy.ClientUpdateStrategy"/>) will observe the cancellation
94+
/// token and terminate the current operation at the next safe checkpoint.
95+
/// A cancellation message is also written to the trace log.
96+
/// </remarks>
9097
public void Cancel()
9198
{
9299
_cts?.Cancel();
@@ -245,6 +252,15 @@ public GeneralUpdateBootstrap SetConfig(Configinfo configInfo)
245252
/// If just a filename (no directory separator), resolves relative to the current directory.
246253
/// Relative or absolute paths are used as-is.
247254
/// </param>
255+
/// <returns>This bootstrap instance for chaining.</returns>
256+
/// <exception cref="ArgumentNullException">Thrown when <paramref name="filePath"/> is <c>null</c> or whitespace.</exception>
257+
/// <exception cref="FileNotFoundException">Thrown when the specified file does not exist.</exception>
258+
/// <exception cref="InvalidOperationException">Thrown when the JSON file cannot be deserialised into a valid <see cref="Configinfo"/>.</exception>
259+
/// <remarks>
260+
/// Reads the file content as UTF-8 JSON, deserialises it into a <see cref="Configinfo"/>
261+
/// using the source-generated JSON serialisation context (<see cref="JsonContext.HttpParameterJsonContext"/>),
262+
/// then delegates to <see cref="SetConfig(Configinfo)"/> for validation and mapping.
263+
/// </remarks>
248264
public GeneralUpdateBootstrap SetConfig(string filePath)
249265
{
250266
if (string.IsNullOrWhiteSpace(filePath))
@@ -282,6 +298,21 @@ public GeneralUpdateBootstrap UseDiffPipeline(Action<DiffPipelineBuilder>? confi
282298
return this;
283299
}
284300

301+
/// <summary>
302+
/// Registers a pre-check callback that is invoked after update information is retrieved
303+
/// but before downloads begin. The callback can inspect the metadata and decide whether
304+
/// to proceed with or abort the update.
305+
/// </summary>
306+
/// <param name="func">A predicate that receives <see cref="UpdateInfoEventArgs"/>
307+
/// and returns <c>true</c> to continue or <c>false</c> to abort the update.</param>
308+
/// <returns>This bootstrap instance for chaining.</returns>
309+
/// <exception cref="ArgumentNullException">Thrown when <paramref name="func"/> is <c>null</c>.</exception>
310+
/// <remarks>
311+
/// The pre-check function is called during the client update strategy's standard workflow,
312+
/// immediately after version comparison and before any packages are downloaded.
313+
/// This allows conditional update logic, such as skipping updates under certain
314+
/// network conditions or user preferences.
315+
/// </remarks>
285316
public GeneralUpdateBootstrap AddListenerUpdatePrecheck(Func<UpdateInfoEventArgs, bool> func)
286317
{
287318
_updatePrecheck = func ?? throw new ArgumentNullException(nameof(func));
@@ -456,24 +487,64 @@ private GeneralUpdateBootstrap AddListener<TArgs>(Action<object, TArgs> action)
456487
return this;
457488
}
458489

490+
/// <summary>
491+
/// Registers a callback for the multi-all-download-completed event, raised when all
492+
/// update files across all versions have been downloaded.
493+
/// </summary>
494+
/// <param name="cb">The callback to invoke.</param>
495+
/// <returns>This bootstrap instance for chaining.</returns>
459496
public GeneralUpdateBootstrap AddListenerMultiAllDownloadCompleted(
460497
Action<object, MultiAllDownloadCompletedEventArgs> cb) => AddListener(cb);
461498

499+
/// <summary>
500+
/// Registers a callback for the multi-download-completed event, raised when a single
501+
/// version's set of files has finished downloading.
502+
/// </summary>
503+
/// <param name="cb">The callback to invoke.</param>
504+
/// <returns>This bootstrap instance for chaining.</returns>
462505
public GeneralUpdateBootstrap AddListenerMultiDownloadCompleted(
463506
Action<object, MultiDownloadCompletedEventArgs> cb) => AddListener(cb);
464507

508+
/// <summary>
509+
/// Registers a callback for the multi-download-error event, raised when an error
510+
/// occurs during batch download.
511+
/// </summary>
512+
/// <param name="cb">The callback to invoke.</param>
513+
/// <returns>This bootstrap instance for chaining.</returns>
465514
public GeneralUpdateBootstrap AddListenerMultiDownloadError(
466515
Action<object, MultiDownloadErrorEventArgs> cb) => AddListener(cb);
467516

517+
/// <summary>
518+
/// Registers a callback for download statistics events, providing real-time throughput
519+
/// and progress information during batch downloads.
520+
/// </summary>
521+
/// <param name="cb">The callback to invoke.</param>
522+
/// <returns>This bootstrap instance for chaining.</returns>
468523
public GeneralUpdateBootstrap AddListenerMultiDownloadStatistics(
469524
Action<object, MultiDownloadStatisticsEventArgs> cb) => AddListener(cb);
470525

526+
/// <summary>
527+
/// Registers a callback for exception events raised during the update workflow.
528+
/// </summary>
529+
/// <param name="cb">The callback to invoke.</param>
530+
/// <returns>This bootstrap instance for chaining.</returns>
471531
public GeneralUpdateBootstrap AddListenerException(
472532
Action<object, ExceptionEventArgs> cb) => AddListener(cb);
473533

534+
/// <summary>
535+
/// Registers a callback for update-information events, providing version metadata
536+
/// retrieved from the server.
537+
/// </summary>
538+
/// <param name="cb">The callback to invoke.</param>
539+
/// <returns>This bootstrap instance for chaining.</returns>
474540
public GeneralUpdateBootstrap AddListenerUpdateInfo(
475541
Action<object, UpdateInfoEventArgs> cb) => AddListener(cb);
476542

543+
/// <summary>
544+
/// Registers a callback for general progress events during the update process.
545+
/// </summary>
546+
/// <param name="cb">The callback to invoke.</param>
547+
/// <returns>This bootstrap instance for chaining.</returns>
477548
public GeneralUpdateBootstrap AddListenerProgress(
478549
Action<object, ProgressEventArgs> cb) => AddListener(cb);
479550

0 commit comments

Comments
 (0)