Plaintext review

src/BitzArt.XDoc/DocumentationElements/DocumentationElement.cs

@@ -23,7 +23,7 @@ public abstract class DocumentationElement : IDocumentationElement
     /// </summary>
     /// <param name="source">The source of the documentation.</param>
     /// <param name="node">The XML node that contains the documentation.</param>
-    protected DocumentationElement(XDoc source, XmlNode? node)
+    internal DocumentationElement(XDoc source, XmlNode? node)
     {
         Source = source;
         Node = node;

src/EntityFrameworkCore/BitzArt.XDoc.EntityFrameworkCore/EntitiesCommentConfigurator.cs → src/EntityFrameworkCore/BitzArt.XDoc.EntityFrameworkCore/EntitiesDocumentationConfigurator.cs

@@ -7,14 +7,14 @@ namespace BitzArt.XDoc;
 /// Configures XML documentation comments for Entity Framework Core entities and their properties.
 /// </summary>
 [PublicAPI]
-public class EntitiesCommentConfigurator
+public class EntitiesDocumentationConfigurator
 {
     private readonly XDoc _xDoc;
 
     /// <summary>
     /// Default constructor.
     /// </summary>
-    public EntitiesCommentConfigurator(XDoc xDoc)
+    public EntitiesDocumentationConfigurator(XDoc xDoc)
     {
         _xDoc = xDoc;
     }
@@ -29,7 +29,14 @@ public void ConfigureComments(ModelBuilder modelBuilder)
 
         foreach (var entityType in entityTypes)
         {
-            var entityComment = _xDoc.Get(entityType.ClrType).ToPlainText();
+            var typeDocumentation = _xDoc.Get(entityType.ClrType);
+
+            if (typeDocumentation is null)
+            {
+                continue;
+            }
+
+            var entityComment = typeDocumentation.ToPlainText();
 
             // For owned entities, we don't set the comment on the entity itself
             // But we will set the comment on the properties
@@ -55,12 +62,19 @@ public void ConfigureComments(ModelBuilder modelBuilder)
 
                 var propertyInfo = entityType.ClrType.GetProperty(property.Name);
 
-                if (propertyInfo == null)
+                if (propertyInfo is null)
                 {
                     return;
                 }
 
-                var propertyComment = _xDoc.Get(propertyInfo).ToPlainText();
+                var propertyDocumentation = _xDoc.Get(propertyInfo);
+
+                if (propertyDocumentation is null)
+                {
+                    continue;
+                }
+
+                var propertyComment = propertyDocumentation.ToPlainText();
 
                 property.SetComment(propertyComment);
             }

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

@@ -51,7 +51,14 @@ public static EntityTypeBuilder<TEntity> HasPropertyComment<TEntity, TProperty>(
         where TEntity : class
         where TCommentTargetEntity : class
     {
-        var comment = xdoc.Get(commentTargetPropertyExpression).ToPlainText();
+        var documentationElement = xdoc.Get(commentTargetPropertyExpression);
+
+        if (documentationElement is null)
+        {
+            return entityTypeBuilder;
+        }
+
+        var comment = documentationElement.ToPlainText();
 
         return entityTypeBuilder.HasPropertyComment(propertyExpression, comment);
     }
@@ -96,7 +103,14 @@ public static EntityTypeBuilder<TEntity> HasPropertyComment<TEntity>(
             throw new InvalidOperationException("The property name is ambiguous.");
         }
 
-        var comment = xdoc.Get(memberInfo.First()).ToPlainText();
+        var documentationElement = xdoc.Get(memberInfo.First());
+
+        if (documentationElement is null)
+        {
+            return entityTypeBuilder;
+        }
+
+        var comment = documentationElement.ToPlainText();
 
         entityTypeBuilder.Property(propertyName).HasComment(comment);
 

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

@@ -29,8 +29,15 @@ public static PropertyBuilder HasComment<TCommentTargetEntity, TCommentTargetPro
         Expression<Func<TCommentTargetEntity, TCommentTargetProperty>> commentTargetPropertyExpression)
         where TCommentTargetEntity : class
     {
-        var comment = xdoc.Get(commentTargetPropertyExpression).ToPlainText();
+        var documentationElement = xdoc.Get(commentTargetPropertyExpression);
 
+        if (documentationElement is null)
+        {
+            return propertyBuilder;
+        }
+
+        var comment = documentationElement.ToPlainText();
+
         return propertyBuilder.HasComment(comment);
     }
 
@@ -51,7 +58,14 @@ public static PropertyBuilder<TProperty> HasComment<TProperty, TCommentTargetEnt
         Expression<Func<TCommentTargetEntity, TCommentTargetProperty>> commentTargetPropertyExpression)
         where TCommentTargetEntity : class
     {
-        var comment = xdoc.Get(commentTargetPropertyExpression).ToPlainText();
+        var documentationElement = xdoc.Get(commentTargetPropertyExpression);
+
+        if (documentationElement is null)
+        {
+            return propertyBuilder;
+        }
+
+        var comment = documentationElement.ToPlainText();
 
         return propertyBuilder.HasComment(comment);
     }

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

@@ -5,7 +5,7 @@
         <ImplicitUsings>enable</ImplicitUsings>
         <Nullable>enable</Nullable>
         <GenerateDocumentationFile>true</GenerateDocumentationFile>
-        <RootNamespace>BitzArt.XDoc</RootNamespace>
+        <RootNamespace>BitzArt.XDoc.PlainText</RootNamespace>
 
         <PackageId>BitzArt.XDoc.PlainText</PackageId>
         <Authors>BitzArt</Authors>

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

@@ -1,6 +1,6 @@
 using System.Reflection;
 
-namespace BitzArt.XDoc;
+namespace BitzArt.XDoc.PlainText;
 
 /// <summary>
 /// Direct inheritance resolver (<c>&lt;inheritdoc/&gt;</c>)
@@ -44,7 +44,7 @@ internal static class InheritanceResolver
             {
                 return found;
             }
-        
+
             var result = FindTargetMember(immediateInterface, sourceMember);
 
             if (result is not null)
@@ -63,7 +63,6 @@ internal static class InheritanceResolver
                 return result;
             }
         }
-
 
         return null;
     }
@@ -89,9 +88,13 @@ [.. methodInfo.GetParameters().Select(p => p.ParameterType)]),
 
     private static IEnumerable<Type> GetImmediateInterfaces(Type type)
     {
-        var inheritedInterfaces = type.GetInterfaces().SelectMany(i => i.GetInterfaces()).ToList();
-        inheritedInterfaces.AddRange(type.BaseType?.GetInterfaces() ?? []);
+        var inheritedInterfaces = type
+            .GetInterfaces()
+            .SelectMany(i => i.GetInterfaces())
+            .Union(type.BaseType?.GetInterfaces() ?? []);
+
+        var result = type.GetInterfaces().Except(inheritedInterfaces);
 
-        return type.GetInterfaces().Except(inheritedInterfaces);
+        return result;
     }
 }

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

@@ -1,38 +1,43 @@
-using JetBrains.Annotations;
-
-namespace BitzArt.XDoc;
-
+namespace BitzArt.XDoc.PlainText;
 
 /// <summary>
-/// Represents and parses XML documentation references (crefs) for types and members.
-/// Handles type references (T:), method references (M:), property references (P:), and field references (F:).
+/// Represents an identifier for types and members in XML documentation comments.
 /// </summary>
-[PublicAPI]
-public record MemberIdentifier
+internal record MemberIdentifier
 {
     /// <summary>
-    /// Initializes a new instance of the <see cref="MemberIdentifier"/> class by parsing a cref string.
+    /// Initializes a new instance of the <see cref="MemberIdentifier"/> class by parsing the given string.
     /// </summary>
-    /// <param name="cref">The cref string to parse (e.g., "T:Namespace.TypeName" or "M:Namespace.TypeName.MethodName").</param>
+    /// <param name="value">The cref string to parse (e.g., "T:Namespace.TypeName" or "M:Namespace.TypeName.MethodName").</param>
     /// <exception cref="ArgumentException">Thrown when the cref format is invalid.</exception>
-    public MemberIdentifier(string cref)
+    private MemberIdentifier(string value)
     {
-        Prefix = cref[..2];
+        if (string.IsNullOrEmpty(value))
+        {
+            throw new ArgumentException("Cref cannot be null or empty", nameof(value));
+        }
+
+        if (value.Length < 3 || value[1] != ':')
+        {
+            throw new ArgumentException($"Invalid cref format: {value}", nameof(value));
+        }
+
+        Prefix = value[..2];
 
-        var lastIndexOf = cref.LastIndexOf('.');
+        var lastIndexOf = value.LastIndexOf('.');
 
         switch (Prefix)
         {
             case "T:":
-                Type = cref.Substring(2, cref.Length - 2);
+                Type = value.Substring(2, value.Length - 2);
                 Member = null;
                 break;
             case "M:" or "P:" or "F:":
-                Type = cref.Substring(2, lastIndexOf - 2);
-                Member = cref.Substring(lastIndexOf + 1, cref.Length - lastIndexOf - 1);
+                Type = value.Substring(2, lastIndexOf - 2);
+                Member = value.Substring(lastIndexOf + 1, value.Length - lastIndexOf - 1);
                 break;
             default:
-                throw new ArgumentException($"Invalid cref: {cref}");
+                throw new ArgumentException($"Invalid value: {value}");
         }
 
         var typeLastIndexOf = Type.LastIndexOf('.');
@@ -76,19 +81,19 @@ public MemberIdentifier(string cref)
     /// Formats the identifier back into a valid cref string.
     /// </summary>
     /// <returns>A string that represents the current object.</returns>
-    public override string ToString() => $"{Prefix}{Type}{(Member != null ? "." + Member : string.Empty)}";
+    public override string ToString() => $"{Prefix}{Type}{(Member is not null ? "." + Member : string.Empty)}";
 
     /// <summary>
     /// Attempts to create a <see cref="MemberIdentifier"/> from a string value.
     /// </summary>
     /// <param name="value">The cref string to parse.</param>
     /// <param name="cref">When this method returns, contains the created <see cref="MemberIdentifier"/> if successful; otherwise, null.</param>
     /// <returns>true if the creation was successful; otherwise, false.</returns>
-    public static bool TryCreate(string? value, out MemberIdentifier? cref)
+    public static bool TryCreate(string value, out MemberIdentifier? cref)
     {
         try
         {
-            cref = new MemberIdentifier(value!);
+            cref = new MemberIdentifier(value);
         }
         catch
         {

src/Render/BitzArt.XDoc.PlainText/PlainTextRenderer.cs

@@ -1,8 +1,9 @@
+using System.Diagnostics;
 using System.Reflection;
 using System.Text;
 using System.Xml;
 
-namespace BitzArt.XDoc;
+namespace BitzArt.XDoc.PlainText;
 
 /// <summary>
 /// Lightweight renderer that converts XML documentation to plain text.
@@ -29,9 +30,9 @@ internal PlainTextRenderer(XDoc xdoc, RendererOptions options)
     /// </summary>
     /// <param name="documentation"></param>
     /// <returns></returns>
-    public string Render(DocumentationElement? documentation)
+    public string Render(IDocumentationElement? documentation)
     {
-        if (documentation == null)
+        if (documentation is null)
         {
             return string.Empty;
         }
@@ -41,7 +42,7 @@ public string Render(DocumentationElement? documentation)
         return Normalize(Render(documentation.Node, target));
     }
 
-    private MemberInfo? GetTarget(DocumentationElement documentation)
+    private MemberInfo? GetTarget(IDocumentationElement documentation)
     {
         if (documentation is IDocumentationElement<Type> typeDocumentation)
         {
@@ -82,7 +83,7 @@ private string Normalize(string input)
             .Where(o => !string.IsNullOrWhiteSpace(o))
             .ToList();
 
-        var separator = _options.Trim ? " " : "\n";
+        var separator = _options.RemoveNamespace ? " " : "\n";
 
         return string.Join(separator, lines);
     }
@@ -95,16 +96,6 @@ private string Normalize(string input)
         _ => node.InnerText
     };
 
-    /// <summary>
-    /// Renders the content of an XML text node to plain text.
-    /// </summary>
-    /// <param name="textNode">The XML text node to render.</param>
-    /// <returns>The plain text representation of the XML text node.</returns>
-    private string RenderTextNode(XmlText textNode)
-    {
-        return textNode.Value ?? string.Empty;
-    }
-
     /// <summary>
     /// Renders the content of an XML element to plain text, including handling child nodes and references.
     /// </summary>
@@ -113,7 +104,7 @@ private string RenderTextNode(XmlText textNode)
     /// <returns>The plain text representation of the XML element.</returns>
     private string RenderXmlElement(XmlElement element, MemberInfo? target)
     {
-        if (element.Attributes["cref"] != null)
+        if (element.Attributes["cref"] is not null)
         {
             // Reference
             return RenderReference(element);
@@ -137,44 +128,59 @@ private string RenderXmlElement(XmlElement element, MemberInfo? target)
 
     private string RenderReference(XmlElement element)
     {
-        MemberIdentifier.TryCreate(element.Attributes["cref"]?.Value, out var cref);
+        MemberIdentifier.TryCreate(element.Attributes["cref"]?.Value!, out var cref);
 
-        if (cref == null)
+        if (cref is null)
         {
             return string.Empty;
         }
-        
+
         var type = _options.RemoveNamespace ? cref.ShortType : cref.Type;
 
         if (cref.IsMember)
         {
             return $"{type}.{cref.Member}";
         }
+
+        if (cref.IsType)
+        {
+            return type;
+        }
 
-        return type;
+        throw new UnreachableException();
     }
 
     private string RenderDirectInheritance(MemberInfo? target)
     {
-        if (target == null)
+        if (target is null)
         {
             return string.Empty;
         }
 
         var targetMember = InheritanceResolver.GetTargetMember(target);
 
-        if (targetMember == null)
+        if (targetMember is null)
         {
             return string.Empty;
         }
 
         var documentationElement = _xdoc.Get(targetMember);
 
-        if (documentationElement == null)
+        if (documentationElement is null)
         {
             return RenderDirectInheritance(targetMember);
         }
 
         return Render(documentationElement);
     }
+
+    /// <summary>
+    /// Renders the content of an XML text node to plain text.
+    /// </summary>
+    /// <param name="textNode">The XML text node to render.</param>
+    /// <returns>The plain text representation of the XML text node.</returns>
+    private static string RenderTextNode(XmlText textNode)
+    {
+        return textNode.Value ?? string.Empty;
+    }
 }