Skip to content

Commit 376d9e0

Browse files
a-gubskiya-gubskiy
authored
Plaintext review (#30)
1 parent 7c0a3a3 commit 376d9e0

File tree

19 files changed

+203
-146
lines changed

19 files changed

+203
-146
lines changed

‎src/BitzArt.XDoc/DocumentationElements/DocumentationElement.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -23,7 +23,7 @@ public abstract class DocumentationElement : IDocumentationElement
2323
/// </summary>
2424
/// <param name="source">The source of the documentation.</param>
2525
/// <param name="node">The XML node that contains the documentation.</param>
26-
protected DocumentationElement(XDoc source, XmlNode? node)
26+
internal DocumentationElement(XDoc source, XmlNode? node)
2727
{
2828
Source = source;
2929
Node = node;

‎src/EntityFrameworkCore/BitzArt.XDoc.EntityFrameworkCore/EntitiesCommentConfigurator.cs renamed to ‎src/EntityFrameworkCore/BitzArt.XDoc.EntityFrameworkCore/EntitiesDocumentationConfigurator.cs

Lines changed: 20 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -7,14 +7,14 @@ namespace BitzArt.XDoc;
77
/// Configures XML documentation comments for Entity Framework Core entities and their properties.
88
/// </summary>
99
[PublicAPI]
10-
public class EntitiesCommentConfigurator
10+
public class EntitiesDocumentationConfigurator
1111
{
1212
private readonly XDoc _xDoc;
1313

1414
/// <summary>
1515
/// Default constructor.
1616
/// </summary>
17-
public EntitiesCommentConfigurator(XDoc xDoc)
17+
public EntitiesDocumentationConfigurator(XDoc xDoc)
1818
{
1919
_xDoc = xDoc;
2020
}
@@ -29,7 +29,14 @@ public void ConfigureComments(ModelBuilder modelBuilder)
2929

3030
foreach (var entityType in entityTypes)
3131
{
32-
var entityComment = _xDoc.Get(entityType.ClrType).ToPlainText();
32+
var typeDocumentation = _xDoc.Get(entityType.ClrType);
33+
34+
if (typeDocumentation is null)
35+
{
36+
continue;
37+
}
38+
39+
var entityComment = typeDocumentation.ToPlainText();
3340

3441
// For owned entities, we don't set the comment on the entity itself
3542
// But we will set the comment on the properties
@@ -55,12 +62,19 @@ public void ConfigureComments(ModelBuilder modelBuilder)
5562

5663
var propertyInfo = entityType.ClrType.GetProperty(property.Name);
5764

58-
if (propertyInfo == null)
65+
if (propertyInfo is null)
66+
{
67+
continue;
68+
}
69+
70+
var propertyDocumentation = _xDoc.Get(propertyInfo);
71+
72+
if (propertyDocumentation is null)
5973
{
60-
return;
74+
continue;
6175
}
6276

63-
var propertyComment = _xDoc.Get(propertyInfo).ToPlainText();
77+
var propertyComment = propertyDocumentation.ToPlainText();
6478

6579
property.SetComment(propertyComment);
6680
}

‎src/EntityFrameworkCore/BitzArt.XDoc.EntityFrameworkCore/Extensions/EntityTypeBuilderExtensions.cs

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -51,7 +51,14 @@ public static EntityTypeBuilder<TEntity> HasPropertyComment<TEntity, TProperty>(
5151
where TEntity : class
5252
where TCommentTargetEntity : class
5353
{
54-
var comment = xdoc.Get(commentTargetPropertyExpression).ToPlainText();
54+
var documentationElement = xdoc.Get(commentTargetPropertyExpression);
55+
56+
if (documentationElement is null)
57+
{
58+
return entityTypeBuilder;
59+
}
60+
61+
var comment = documentationElement.ToPlainText();
5562

5663
return entityTypeBuilder.HasPropertyComment(propertyExpression, comment);
5764
}
@@ -96,7 +103,14 @@ public static EntityTypeBuilder<TEntity> HasPropertyComment<TEntity>(
96103
throw new InvalidOperationException("The property name is ambiguous.");
97104
}
98105

99-
var comment = xdoc.Get(memberInfo.First()).ToPlainText();
106+
var documentationElement = xdoc.Get(memberInfo.First());
107+
108+
if (documentationElement is null)
109+
{
110+
return entityTypeBuilder;
111+
}
112+
113+
var comment = documentationElement.ToPlainText();
100114

101115
entityTypeBuilder.Property(propertyName).HasComment(comment);
102116

‎src/EntityFrameworkCore/BitzArt.XDoc.EntityFrameworkCore/Extensions/PropertyBuilderExtensions.cs

Lines changed: 16 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,8 +29,15 @@ public static PropertyBuilder HasComment<TCommentTargetEntity, TCommentTargetPro
2929
Expression<Func<TCommentTargetEntity, TCommentTargetProperty>> commentTargetPropertyExpression)
3030
where TCommentTargetEntity : class
3131
{
32-
var comment = xdoc.Get(commentTargetPropertyExpression).ToPlainText();
32+
var documentationElement = xdoc.Get(commentTargetPropertyExpression);
3333

34+
if (documentationElement is null)
35+
{
36+
return propertyBuilder;
37+
}
38+
39+
var comment = documentationElement.ToPlainText();
40+
3441
return propertyBuilder.HasComment(comment);
3542
}
3643

@@ -51,7 +58,14 @@ public static PropertyBuilder<TProperty> HasComment<TProperty, TCommentTargetEnt
5158
Expression<Func<TCommentTargetEntity, TCommentTargetProperty>> commentTargetPropertyExpression)
5259
where TCommentTargetEntity : class
5360
{
54-
var comment = xdoc.Get(commentTargetPropertyExpression).ToPlainText();
61+
var documentationElement = xdoc.Get(commentTargetPropertyExpression);
62+
63+
if (documentationElement is null)
64+
{
65+
return propertyBuilder;
66+
}
67+
68+
var comment = documentationElement.ToPlainText();
5569

5670
return propertyBuilder.HasComment(comment);
5771
}

‎src/Render/BitzArt.XDoc.PlainText/BitzArt.XDoc.PlainText.csproj

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -5,7 +5,7 @@
55
<ImplicitUsings>enable</ImplicitUsings>
66
<Nullable>enable</Nullable>
77
<GenerateDocumentationFile>true</GenerateDocumentationFile>
8-
<RootNamespace>BitzArt.XDoc</RootNamespace>
8+
<RootNamespace>BitzArt.XDoc.PlainText</RootNamespace>
99

1010
<PackageId>BitzArt.XDoc.PlainText</PackageId>
1111
<Authors>BitzArt</Authors>

‎src/Render/BitzArt.XDoc.PlainText/InheritanceResolver.cs

Lines changed: 9 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
using System.Reflection;
22

3-
namespace BitzArt.XDoc;
3+
namespace BitzArt.XDoc.PlainText;
44

55
/// <summary>
66
/// Direct inheritance resolver (<c>&lt;inheritdoc/&gt;</c>)
@@ -44,7 +44,7 @@ internal static class InheritanceResolver
4444
{
4545
return found;
4646
}
47-
47+
4848
var result = FindTargetMember(immediateInterface, sourceMember);
4949

5050
if (result is not null)
@@ -63,7 +63,6 @@ internal static class InheritanceResolver
6363
return result;
6464
}
6565
}
66-
6766

6867
return null;
6968
}
@@ -89,9 +88,13 @@ [.. methodInfo.GetParameters().Select(p => p.ParameterType)]),
8988

9089
private static IEnumerable<Type> GetImmediateInterfaces(Type type)
9190
{
92-
var inheritedInterfaces = type.GetInterfaces().SelectMany(i => i.GetInterfaces()).ToList();
93-
inheritedInterfaces.AddRange(type.BaseType?.GetInterfaces() ?? []);
91+
var inheritedInterfaces = type
92+
.GetInterfaces()
93+
.SelectMany(i => i.GetInterfaces())
94+
.Union(type.BaseType?.GetInterfaces() ?? []);
95+
96+
var result = type.GetInterfaces().Except(inheritedInterfaces);
9497

95-
return type.GetInterfaces().Except(inheritedInterfaces);
98+
return result;
9699
}
97100
}

‎src/Render/BitzArt.XDoc.PlainText/MemberIdentifier.cs

Lines changed: 25 additions & 20 deletions
Original file line numberDiff line numberDiff line change
@@ -1,38 +1,43 @@
1-
using JetBrains.Annotations;
2-
3-
namespace BitzArt.XDoc;
4-
1+
namespace BitzArt.XDoc.PlainText;
52

63
/// <summary>
7-
/// Represents and parses XML documentation references (crefs) for types and members.
8-
/// Handles type references (T:), method references (M:), property references (P:), and field references (F:).
4+
/// Represents an identifier for types and members in XML documentation comments.
95
/// </summary>
10-
[PublicAPI]
11-
public record MemberIdentifier
6+
internal record MemberIdentifier
127
{
138
/// <summary>
14-
/// Initializes a new instance of the <see cref="MemberIdentifier"/> class by parsing a cref string.
9+
/// Initializes a new instance of the <see cref="MemberIdentifier"/> class by parsing the given string.
1510
/// </summary>
16-
/// <param name="cref">The cref string to parse (e.g., "T:Namespace.TypeName" or "M:Namespace.TypeName.MethodName").</param>
11+
/// <param name="value">The cref string to parse (e.g., "T:Namespace.TypeName" or "M:Namespace.TypeName.MethodName").</param>
1712
/// <exception cref="ArgumentException">Thrown when the cref format is invalid.</exception>
18-
public MemberIdentifier(string cref)
13+
private MemberIdentifier(string value)
1914
{
20-
Prefix = cref[..2];
15+
if (string.IsNullOrEmpty(value))
16+
{
17+
throw new ArgumentException("Cref cannot be null or empty", nameof(value));
18+
}
19+
20+
if (value.Length < 3 || value[1] != ':')
21+
{
22+
throw new ArgumentException($"Invalid cref format: {value}", nameof(value));
23+
}
24+
25+
Prefix = value[..2];
2126

22-
var lastIndexOf = cref.LastIndexOf('.');
27+
var lastIndexOf = value.LastIndexOf('.');
2328

2429
switch (Prefix)
2530
{
2631
case "T:":
27-
Type = cref.Substring(2, cref.Length - 2);
32+
Type = value.Substring(2, value.Length - 2);
2833
Member = null;
2934
break;
3035
case "M:" or "P:" or "F:":
31-
Type = cref.Substring(2, lastIndexOf - 2);
32-
Member = cref.Substring(lastIndexOf + 1, cref.Length - lastIndexOf - 1);
36+
Type = value.Substring(2, lastIndexOf - 2);
37+
Member = value.Substring(lastIndexOf + 1, value.Length - lastIndexOf - 1);
3338
break;
3439
default:
35-
throw new ArgumentException($"Invalid cref: {cref}");
40+
throw new ArgumentException($"Invalid value: {value}");
3641
}
3742

3843
var typeLastIndexOf = Type.LastIndexOf('.');
@@ -76,19 +81,19 @@ public MemberIdentifier(string cref)
7681
/// Formats the identifier back into a valid cref string.
7782
/// </summary>
7883
/// <returns>A string that represents the current object.</returns>
79-
public override string ToString() => $"{Prefix}{Type}{(Member != null ? "." + Member : string.Empty)}";
84+
public override string ToString() => $"{Prefix}{Type}{(Member is not null ? "." + Member : string.Empty)}";
8085

8186
/// <summary>
8287
/// Attempts to create a <see cref="MemberIdentifier"/> from a string value.
8388
/// </summary>
8489
/// <param name="value">The cref string to parse.</param>
8590
/// <param name="cref">When this method returns, contains the created <see cref="MemberIdentifier"/> if successful; otherwise, null.</param>
8691
/// <returns>true if the creation was successful; otherwise, false.</returns>
87-
public static bool TryCreate(string? value, out MemberIdentifier? cref)
92+
public static bool TryCreate(string value, out MemberIdentifier? cref)
8893
{
8994
try
9095
{
91-
cref = new MemberIdentifier(value!);
96+
cref = new MemberIdentifier(value);
9297
}
9398
catch
9499
{

0 commit comments

Comments
 (0)