Merge pull request #2412 from KathleenDollard/RemoveGetSetDescriptionFromHelpSubsystem

refactor: Remove Get/Set Description on Helper subsystem; add Get to AnnotationAccessor

Author: KathleenDollard

src/System.CommandLine.Subsystems.Tests/AlternateSubsystems.cs

@@ -2,8 +2,6 @@
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System.CommandLine.Directives;
-using System.CommandLine.Subsystems;
-using System.CommandLine.Subsystems.Annotations;
 
 namespace System.CommandLine.Subsystems.Tests
 {
@@ -33,9 +31,9 @@ public VersionThatUsesHelpData(CliSymbol symbol)
             protected override CliExit Execute(PipelineContext pipelineContext)
             {
                 var help = pipelineContext.Pipeline.Help ?? throw new InvalidOperationException("Help cannot be null for this subsystem to work");
-                var data = help.GetDescription(Symbol);
+                help.Description.TryGet(Symbol, out var description);
 
-                pipelineContext.ConsoleHack.WriteLine(data);
+                pipelineContext.ConsoleHack.WriteLine(description);
                 pipelineContext.AlreadyHandled = true;
                 return CliExit.SuccessfullyHandled(pipelineContext.ParseResult);
             }
@@ -68,11 +66,11 @@ protected override CliExit TearDown(CliExit cliExit)
         }
 
         internal class StringDirectiveSubsystem(IAnnotationProvider? annotationProvider = null)
-           : DirectiveSubsystem("other",SubsystemKind.Diagram, annotationProvider)
+           : DirectiveSubsystem("other", SubsystemKind.Diagram, annotationProvider)
         { }
 
         internal class BooleanDirectiveSubsystem(IAnnotationProvider? annotationProvider = null)
-           : DirectiveSubsystem("diagram", SubsystemKind.Diagram,  annotationProvider)
+           : DirectiveSubsystem("diagram", SubsystemKind.Diagram, annotationProvider)
         { }
 
     }

src/System.CommandLine.Subsystems/HelpSubsystem.cs

@@ -1,4 +1,4 @@
-// Copyright (c) .NET Foundation and contributors. All rights reserved.
+// Copyright (c) .NET Foundation and contributors. All rights reserved.
 // Licensed under the MIT license. See LICENSE file in the project root for full license information.
 
 using System.CommandLine.Subsystems.Annotations;
@@ -24,14 +24,6 @@ public class HelpSubsystem(IAnnotationProvider? annotationProvider = null)
         Arity = ArgumentArity.Zero
     };
 
-    public void SetDescription(CliSymbol symbol, string description)
-        => SetAnnotation(symbol, HelpAnnotations.Description, description);
-
-    public string GetDescription(CliSymbol symbol)
-        => TryGetAnnotation<string>(symbol, HelpAnnotations.Description, out var value)
-            ? value
-            : "";
-
     public AnnotationAccessor<string> Description
         => new(this, HelpAnnotations.Description);
 

src/System.CommandLine.Subsystems/Subsystems/Annotations/AnnotationAccessor.cs

@@ -8,12 +8,31 @@ namespace System.CommandLine.Subsystems.Annotations;
 /// <summary>
 /// Allows associating an annotation with a <see cref="CliSymbol"/>. The annotation will be stored by the accessor's owner <see cref="CliSubsystem"/>.
 /// </summary>
+/// <remarks>
+/// The annotation will be stored by the accessor's owner <see cref="CliSubsystem"/>. 
+/// </summary>
+/// <typeparam name="TValue">The type of value to be stored</typeparam>
+/// <param name="owner">The subsystem that this annotation store data for.</param>
+/// <param name="id">The identifier for this annotation, since subsystems may have multiple annotations.</param>
 public struct AnnotationAccessor<TValue>(CliSubsystem owner, AnnotationId<TValue> id)
 {
     /// <summary>
-    /// The ID of the annotation
+    /// The identifier for this annotation, since subsystems may have multiple annotations.
+    /// </summary>
+    public AnnotationId<TValue> Id { get; } = id;
+
+    /// <summary>
+    /// Store a value for the annotation and symbol
+    /// </summary>
+    /// <param name="symbol">The CliSymbol the value is for.</param>
+    /// <param name="value">The value to store.</param>
+    public readonly void Set(CliSymbol symbol, TValue value) => owner.SetAnnotation(symbol, Id, value);
+
+    /// <summary>
+    /// Retrieve the value for the annotation and symbol
     /// </summary>
-    public AnnotationId<TValue> Id { get; }
-    public readonly void Set(CliSymbol symbol, TValue value) => owner.SetAnnotation(symbol, id, value);
-    public readonly bool TryGet(CliSymbol symbol, [NotNullWhen(true)] out TValue? value) => owner.TryGetAnnotation(symbol, id, out value);
+    /// <param name="symbol">The CliSymbol the value is for.</param>
+    /// <param name="value">The value to retrieve.</param>
+    /// <returns>True if the value was found, false otherwise.</returns>
+    public readonly bool TryGet(CliSymbol symbol, [NotNullWhen(true)] out TValue? value) => owner.TryGetAnnotation(symbol, Id, out value);
 }