Skip to content

Commit b341ef9

Browse files
Sergio0694Sergio0694
authored
Merge pull request #653 from CommunityToolkit/dev/generator-xml-docs
Improve XML docs over generated code
2 parents b8df95a + d4d3c26 commit b341ef9

File tree

5 files changed

+276
-21
lines changed

5 files changed

+276
-21
lines changed

‎src/CommunityToolkit.Mvvm.SourceGenerators/ComponentModel/ObservablePropertyGenerator.Execute.cs

Lines changed: 25 additions & 12 deletions
Original file line numberDiff line numberDiff line change
@@ -1113,13 +1113,13 @@ public static ImmutableArray<MemberDeclarationSyntax> GetOnPropertyChangeMethods
11131113
/// <summary>
11141114
/// Gets a <see cref="CompilationUnitSyntax"/> instance with the cached args of a specified type.
11151115
/// </summary>
1116-
/// <param name="ContainingTypeName">The name of the generated type.</param>
1117-
/// <param name="ArgsTypeName">The argument type name.</param>
1116+
/// <param name="containingTypeName">The name of the generated type.</param>
1117+
/// <param name="argsTypeName">The argument type name.</param>
11181118
/// <param name="names">The sequence of property names to cache args for.</param>
11191119
/// <returns>A <see cref="CompilationUnitSyntax"/> instance with the sequence of cached args, if any.</returns>
11201120
private static CompilationUnitSyntax? GetKnownPropertyChangingOrChangedArgsSyntax(
1121-
string ContainingTypeName,
1122-
string ArgsTypeName,
1121+
string containingTypeName,
1122+
string argsTypeName,
11231123
ImmutableArray<string> names)
11241124
{
11251125
if (names.IsEmpty)
@@ -1134,6 +1134,10 @@ public static ImmutableArray<MemberDeclarationSyntax> GetOnPropertyChangeMethods
11341134
// #nullable enable
11351135
// namespace CommunityToolkit.Mvvm.ComponentModel.__Internals
11361136
// {
1137+
// /// <summary>
1138+
// /// A helper type providing cached, reusable <see cref="<ARGS_TYPE_NAME>"/> instances
1139+
// /// for all properties generated with <see cref="global::CommunityToolkit.Mvvm.ComponentModel.ObservablePropertyAttribute"/>.
1140+
// /// </summary>
11371141
// [global::System.CodeDom.Compiler.GeneratedCode("...", "...")]
11381142
// [global::System.Diagnostics.DebuggerNonUserCode]
11391143
// [global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
@@ -1150,14 +1154,19 @@ public static ImmutableArray<MemberDeclarationSyntax> GetOnPropertyChangeMethods
11501154
Comment("// <auto-generated/>"),
11511155
Trivia(PragmaWarningDirectiveTrivia(Token(SyntaxKind.DisableKeyword), true)),
11521156
Trivia(NullableDirectiveTrivia(Token(SyntaxKind.EnableKeyword), true)))).AddMembers(
1153-
ClassDeclaration(ContainingTypeName).AddModifiers(
1157+
ClassDeclaration(containingTypeName).AddModifiers(
11541158
Token(SyntaxKind.InternalKeyword),
11551159
Token(SyntaxKind.StaticKeyword)).AddAttributeLists(
11561160
AttributeList(SingletonSeparatedList(
11571161
Attribute(IdentifierName($"global::System.CodeDom.Compiler.GeneratedCode"))
11581162
.AddArgumentListArguments(
11591163
AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ObservablePropertyGenerator).FullName))),
1160-
AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ObservablePropertyGenerator).Assembly.GetName().Version.ToString())))))),
1164+
AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ObservablePropertyGenerator).Assembly.GetName().Version.ToString()))))))
1165+
.WithOpenBracketToken(Token(TriviaList(
1166+
Comment("/// <summary>"),
1167+
Comment($"/// A helper type providing cached, reusable <see cref=\"{argsTypeName}\"/> instances"),
1168+
Comment("/// for all properties generated with <see cref=\"global::CommunityToolkit.Mvvm.ComponentModel.ObservablePropertyAttribute\"/>."),
1169+
Comment("/// </summary>")), SyntaxKind.OpenBracketToken, TriviaList())),
11611170
AttributeList(SingletonSeparatedList(Attribute(IdentifierName("global::System.Diagnostics.DebuggerNonUserCode")))),
11621171
AttributeList(SingletonSeparatedList(Attribute(IdentifierName("global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage")))),
11631172
AttributeList(SingletonSeparatedList(
@@ -1168,31 +1177,32 @@ public static ImmutableArray<MemberDeclarationSyntax> GetOnPropertyChangeMethods
11681177
AttributeArgument(LiteralExpression(
11691178
SyntaxKind.StringLiteralExpression,
11701179
Literal("This type is not intended to be used directly by user code")))))))
1171-
.AddMembers(names.Select(name => CreateFieldDeclaration(ArgsTypeName, name)).ToArray())))
1180+
.AddMembers(names.Select(name => CreateFieldDeclaration(argsTypeName, name)).ToArray())))
11721181
.NormalizeWhitespace();
11731182
}
11741183

11751184
/// <summary>
11761185
/// Creates a field declaration for a cached property changing/changed name.
11771186
/// </summary>
1178-
/// <param name="typeName">The field type name (either <see cref="PropertyChangedEventArgs"/> or <see cref="PropertyChangingEventArgs"/>).</param>
1187+
/// <param name="fullyQualifiedTypeName">The field fully qualified type name (either <see cref="PropertyChangedEventArgs"/> or <see cref="PropertyChangingEventArgs"/>).</param>
11791188
/// <param name="propertyName">The name of the cached property name.</param>
11801189
/// <returns>A <see cref="FieldDeclarationSyntax"/> instance for the input cached property name.</returns>
1181-
private static FieldDeclarationSyntax CreateFieldDeclaration(string typeName, string propertyName)
1190+
private static FieldDeclarationSyntax CreateFieldDeclaration(string fullyQualifiedTypeName, string propertyName)
11821191
{
11831192
// Create a static field with a cached property changed/changing argument for a specified property.
11841193
// This code produces a field declaration as follows:
11851194
//
1195+
// /// <summary>The cached <see cref="<TYPE_NAME>"/> instance for all "<PROPERTY_NAME>" generated properties.</summary>
11861196
// [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
11871197
// [global::System.Obsolete("This field is not intended to be referenced directly by user code")]
11881198
// public static readonly <ARG_TYPE> <PROPERTY_NAME> = new("<PROPERTY_NAME>");
11891199
return
11901200
FieldDeclaration(
1191-
VariableDeclaration(IdentifierName(typeName))
1201+
VariableDeclaration(IdentifierName(fullyQualifiedTypeName))
11921202
.AddVariables(
11931203
VariableDeclarator(Identifier(propertyName))
11941204
.WithInitializer(EqualsValueClause(
1195-
ObjectCreationExpression(IdentifierName(typeName))
1205+
ObjectCreationExpression(IdentifierName(fullyQualifiedTypeName))
11961206
.AddArgumentListArguments(Argument(
11971207
LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(propertyName))))))))
11981208
.AddModifiers(
@@ -1202,7 +1212,10 @@ private static FieldDeclarationSyntax CreateFieldDeclaration(string typeName, st
12021212
.AddAttributeLists(
12031213
AttributeList(SingletonSeparatedList(
12041214
Attribute(IdentifierName("global::System.ComponentModel.EditorBrowsable")).AddArgumentListArguments(
1205-
AttributeArgument(ParseExpression("global::System.ComponentModel.EditorBrowsableState.Never"))))),
1215+
AttributeArgument(ParseExpression("global::System.ComponentModel.EditorBrowsableState.Never")))))
1216+
.WithOpenBracketToken(Token(TriviaList(
1217+
Comment($"/// <summary>The cached <see cref=\"{fullyQualifiedTypeName}\"/> instance for all \"{propertyName}\" generated properties.</summary>")),
1218+
SyntaxKind.OpenBracketToken, TriviaList())),
12061219
AttributeList(SingletonSeparatedList(
12071220
Attribute(IdentifierName("global::System.Obsolete")).AddArgumentListArguments(
12081221
AttributeArgument(LiteralExpression(

‎src/CommunityToolkit.Mvvm.SourceGenerators/ComponentModel/ObservableValidatorValidateAllPropertiesGenerator.Execute.cs

Lines changed: 23 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -96,6 +96,9 @@ public static CompilationUnitSyntax GetSyntax(bool isDynamicallyAccessedMembersA
9696

9797
// Prepare the base attributes with are always present:
9898
//
99+
// /// <summary>
100+
// /// A helper type with generated validation stubs for types deriving from <see cref="global::CommunityToolkit.Mvvm.ComponentModel.ObservableValidator"/>.
101+
// /// </summary>
99102
// [global::System.CodeDom.Compiler.GeneratedCode("...", "...")]
100103
// [global::System.Diagnostics.DebuggerNonUserCode]
101104
// [global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage]
@@ -105,7 +108,11 @@ public static CompilationUnitSyntax GetSyntax(bool isDynamicallyAccessedMembersA
105108
AttributeList(SingletonSeparatedList(
106109
Attribute(IdentifierName($"global::System.CodeDom.Compiler.GeneratedCode")).AddArgumentListArguments(
107110
AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ObservableValidatorValidateAllPropertiesGenerator).FullName))),
108-
AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ObservableValidatorValidateAllPropertiesGenerator).Assembly.GetName().Version.ToString())))))));
111+
AttributeArgument(LiteralExpression(SyntaxKind.StringLiteralExpression, Literal(typeof(ObservableValidatorValidateAllPropertiesGenerator).Assembly.GetName().Version.ToString()))))))
112+
.WithOpenBracketToken(Token(TriviaList(
113+
Comment("/// <summary>"),
114+
Comment("/// A helper type with generated validation stubs for types deriving from <see cref=\"global::CommunityToolkit.Mvvm.ComponentModel.ObservableValidator\"/>."),
115+
Comment("/// </summary>")), SyntaxKind.OpenBracketToken, TriviaList())));
109116
attributes.Add(AttributeList(SingletonSeparatedList(Attribute(IdentifierName("global::System.Diagnostics.DebuggerNonUserCode")))));
110117
attributes.Add(AttributeList(SingletonSeparatedList(Attribute(IdentifierName("global::System.Diagnostics.CodeAnalysis.ExcludeFromCodeCoverage")))));
111118
attributes.Add(
@@ -176,8 +183,14 @@ public static CompilationUnitSyntax GetSyntax(ValidationInfo validationInfo)
176183
// #pragma warning disable
177184
// namespace CommunityToolkit.Mvvm.ComponentModel.__Internals
178185
// {
186+
// /// <inheritdoc/>
179187
// partial class __ObservableValidatorExtensions
180188
// {
189+
// /// <summary>
190+
// /// Creates a validation stub for <see cref="<INSTANCE_TYPE>"/> objects.
191+
// /// </summary>
192+
// /// <param name="_">Dummy parameter, only used to disambiguate the method signature.</param>
193+
// /// <returns>A validation stub for <see cref="<INSTANCE_TYPE>"/> objects.</returns>
181194
// [global::System.ComponentModel.EditorBrowsable(global::System.ComponentModel.EditorBrowsableState.Never)]
182195
// [global::System.Obsolete("This method is not intended to be called directly by user code")]
183196
// public static global::System.Action<object> CreateAllPropertiesValidator(<INSTANCE_TYPE> _)
@@ -197,13 +210,20 @@ public static CompilationUnitSyntax GetSyntax(ValidationInfo validationInfo)
197210
NamespaceDeclaration(IdentifierName("CommunityToolkit.Mvvm.ComponentModel.__Internals")).WithLeadingTrivia(TriviaList(
198211
Comment("// <auto-generated/>"),
199212
Trivia(PragmaWarningDirectiveTrivia(Token(SyntaxKind.DisableKeyword), true)))).AddMembers(
200-
ClassDeclaration("__ObservableValidatorExtensions").AddModifiers(Token(SyntaxKind.PartialKeyword)).AddMembers(
213+
ClassDeclaration("__ObservableValidatorExtensions").AddModifiers(
214+
Token(TriviaList(Comment("/// <inheritdoc/>")), SyntaxKind.PartialKeyword, TriviaList())).AddMembers(
201215
MethodDeclaration(
202216
GenericName("global::System.Action").AddTypeArgumentListArguments(PredefinedType(Token(SyntaxKind.ObjectKeyword))),
203217
Identifier("CreateAllPropertiesValidator")).AddAttributeLists(
204218
AttributeList(SingletonSeparatedList(
205219
Attribute(IdentifierName("global::System.ComponentModel.EditorBrowsable")).AddArgumentListArguments(
206-
AttributeArgument(ParseExpression("global::System.ComponentModel.EditorBrowsableState.Never"))))),
220+
AttributeArgument(ParseExpression("global::System.ComponentModel.EditorBrowsableState.Never")))))
221+
.WithOpenBracketToken(Token(TriviaList(
222+
Comment("/// <summary>"),
223+
Comment($"/// Creates a validation stub for <see cref=\"{validationInfo.TypeName}\"/> objects."),
224+
Comment("/// </summary>"),
225+
Comment("/// <param name=\"_\">Dummy parameter, only used to disambiguate the method signature.</param>"),
226+
Comment($"/// <returns>A validation stub for <see cref=\"{validationInfo.TypeName}\"/> objects.</returns>")), SyntaxKind.OpenBracketToken, TriviaList())),
207227
AttributeList(SingletonSeparatedList(
208228
Attribute(IdentifierName("global::System.Obsolete")).AddArgumentListArguments(
209229
AttributeArgument(LiteralExpression(

0 commit comments

Comments
 (0)