From 6162f8d16f2202d491c82b57f36a3bdbeed943b9 Mon Sep 17 00:00:00 2001 From: Lala Sabathil Date: Tue, 19 Dec 2023 11:44:49 +0100 Subject: [PATCH] chore: docs for tools and minor fixes --- .../DisCatSharp.Analyzer/AttributeAnalyzer.cs | 66 ++++++++++++++++++- 1 file changed, 63 insertions(+), 3 deletions(-) diff --git a/DisCatSharp.Tools/DisCatSharp.Analyzer/DisCatSharp.Analyzer/AttributeAnalyzer.cs b/DisCatSharp.Tools/DisCatSharp.Analyzer/DisCatSharp.Analyzer/AttributeAnalyzer.cs index d28055bb6..11483f938 100644 --- a/DisCatSharp.Tools/DisCatSharp.Analyzer/DisCatSharp.Analyzer/AttributeAnalyzer.cs +++ b/DisCatSharp.Tools/DisCatSharp.Analyzer/DisCatSharp.Analyzer/AttributeAnalyzer.cs @@ -16,7 +16,14 @@ namespace DisCatSharp.Analyzer [DiagnosticAnalyzer(LanguageNames.CSharp)] public class AttributeAnalyzer : DiagnosticAnalyzer { + /// + /// The diagnostic ID prefix. + /// public const string DIAGNOSTIC_ID_PREFIX = "DCS"; + + /// + /// The diagnostic category. + /// public const string CATEGORY = "Usage"; private static readonly LocalizableString s_titleExperimental = new LocalizableResourceString(nameof(Resources.AnalyzerTitleExperimental), Resources.ResourceManager, typeof(Resources)); @@ -89,9 +96,16 @@ public class AttributeAnalyzer : DiagnosticAnalyzer private static readonly DiagnosticDescriptor s_requiresFeatureRule = new DiagnosticDescriptor(DIAGNOSTIC_ID_PREFIX + "0200", s_titleRequiresFeature, s_messageFormatRequiresFeature, CATEGORY, DiagnosticSeverity.Warning, true, s_descriptionRequiresFeature, "https://docs.dcs.aitsys.dev/vs/analyzer/dcs/0200"); + /// + /// Returns a set of descriptors for the diagnostics that this analyzer is capable of producing. + /// public override ImmutableArray SupportedDiagnostics => ImmutableArray.Create(s_experimentalRule, s_deprecatedRule, s_discordInExperimentRule, s_discordDeprecatedRule, s_discordUnreleasedRule, s_requiresFeatureRule); + /// + /// Called once at session start to register actions in the analysis context. + /// + /// The analysis context. public override void Initialize(AnalysisContext context) { context.ConfigureGeneratedCodeAnalysis(GeneratedCodeAnalysisFlags.Analyze | GeneratedCodeAnalysisFlags.ReportDiagnostics); @@ -109,6 +123,10 @@ public override void Initialize(AnalysisContext context) context.RegisterSyntaxNodeAction(StatusAnalyzer, SyntaxKind.SimpleMemberAccessExpression); } + /// + /// Analyzes the status of various components. + /// + /// The syntac node analysis context. private static void StatusAnalyzer(SyntaxNodeAnalysisContext context) { var invocation = context.Node; @@ -175,6 +193,10 @@ private static void StatusAnalyzer(SyntaxNodeAnalysisContext context) return; } + /// + /// Analyzes the experimental state of various components. + /// + /// The symbol analysis context. private static void ExperimentalAnalyzer(SymbolAnalysisContext context) { Console.WriteLine(new LocalizableResourceString(nameof(Resources.Handling), Resources.ResourceManager, typeof(Resources)) + context.Symbol.Kind.ToString()); @@ -182,11 +204,15 @@ private static void ExperimentalAnalyzer(SymbolAnalysisContext context) where x.IsInSource select x.SourceTree; var declaration = context.Symbol; + + // ReSharper disable HeuristicUnreachableCode + // ReSharper disable once ConditionIsAlwaysTrueOrFalse if (null == declaration) { Console.WriteLine(new LocalizableResourceString(nameof(Resources.Faulty), Resources.ResourceManager, typeof(Resources))); return; } + // ReSharper enable HeuristicUnreachableCode var attributes = declaration.GetAttributes(); @@ -248,6 +274,13 @@ where x.IsInSource return; } + /// + /// Checks if the attribute is the desired attribute. + /// + /// The current semantic model. + /// >The current attribute data. + /// The target attribute type to check for. + /// Whether the contains the . private static bool IsRequiredAttribute(SemanticModel semanticModel, AttributeData attribute, Type desiredAttributeType) { if (desiredAttributeType.FullName is null) @@ -259,14 +292,27 @@ private static bool IsRequiredAttribute(SemanticModel semanticModel, AttributeDa return result; } + /// + /// Gets the message from the attribute. + /// + /// The current attribute data. + /// The message. private static string GetMessage(AttributeData attribute) => attribute.ConstructorArguments.Length < 1 ? "Do not use in production." : attribute.ConstructorArguments[0].Value as string; + /// + /// Gets the feature message from the attribute. + /// + /// The current attribute data. + /// The message. private static string GetFeatureMessage(AttributeData attribute) { - var featureReqEnum = (Features)attribute.ConstructorArguments[0].Value; + if (attribute is null) + return string.Empty; + + var featureReqEnum = (Features)attribute.ConstructorArguments[0].Value!; var description = attribute.ConstructorArguments.Length > 1 ? attribute.ConstructorArguments[1].Value as string : "No additional information."; @@ -274,10 +320,19 @@ private static string GetFeatureMessage(AttributeData attribute) } } + /// + /// Represents a various helper methods. + /// internal static class Helpers { + /// + /// Gets the feature strings. + /// internal static Dictionary FeaturesStrings { get; set; } + /// + /// Initializes the class. + /// static Helpers() { FeaturesStrings = new Dictionary(); @@ -289,12 +344,17 @@ static Helpers() { var xsv = xv.ToString(); var xmv = ti.DeclaredMembers.FirstOrDefault(xm => xm.Name == xsv); - var xav = xmv.GetCustomAttribute(); + var xav = xmv?.GetCustomAttribute(); - FeaturesStrings[xv] = xav.Description; + FeaturesStrings[xv] = xav?.Description ?? "No description given."; } } + /// + /// Converts a feature enum to a string. + /// + /// The feature enum to convert. + /// The string representation of the feature enum. public static string ToFeaturesString(this Features features) { var strs = FeaturesStrings