feat: render enum field remarks and obsolete attribute

samples/seed/dotnet/project/Project/Class1.cs

@@ -160,4 +160,33 @@ public void Issue1887() { }
     /// $$\left\{\begin{matrix}a, a<b \\ b, b>a\\ \end{matrix} \right.$$
     /// </summary>
     public static double Issue9216() => 0.0;
+
+    public enum Issue9260
+    {
+        /// <summary>
+        /// This is a regular enum value.
+        /// </summary>
+        /// <remarks>
+        /// This is a remarks section. Very important remarks about Value go here.
+        /// </remarks>
+        Value,
+
+        /// <summary>
+        /// This is old and unused. You shouldn't use it anymore.
+        /// </summary>
+        /// <remarks>
+        /// Don't use this, seriously! Use Value instead.
+        /// </remarks>
+        [Obsolete]
+        OldAndUnusedValue,
+
+        /// <summary>
+        /// This is old and unused. You shouldn't use it anymore.
+        /// </summary>
+        /// <remarks>
+        /// Don't use this, seriously! Use Value instead.
+        /// </remarks>
+        [Obsolete("Use Value")]
+        OldAndUnusedValue2,
+    }
 }

src/Docfx.Build/ApiPage/ApiPageHtmlTemplate.cs

@@ -4,6 +4,7 @@
 #if NET7_0_OR_GREATER
 
 using System.Net;
+using OneOf;
 using static Docfx.Build.HtmlTemplate;
 
 #nullable enable
@@ -47,28 +48,42 @@ HtmlTemplate Api(Api api)
                 ? default
                 : UnsafeHtml(string.Join(" ", value.metadata.Select(m => $"data-{WebUtility.HtmlEncode(m.Key)}='{WebUtility.HtmlEncode(m.Value)}'")));
 
-            var isDeprecated = value.deprecated?.Value switch
+            var (level, title) = api.Value switch
             {
-                bool b when b => true,
-                string s => true,
-                _ => false,
+                Api1 a1 => (1, a1.api1),
+                Api2 a2 => (2, a2.api2),
+                Api3 a3 => (3, a3.api3),
+                Api4 a4 => (4, a4.api4),
             };
-            var deprecated = isDeprecated ? Html($" <span class='badge rounded-pill text-bg-danger' style='font-size: .5em; vertical-align: middle'>Deprecated</span>") : default;
-            var deprecatedReason = value.deprecated?.Value is string ds && !string.IsNullOrEmpty(ds)
-                ? Html($"\n<div class='alert alert-warning' role='alert'>{UnsafeHtml(markup(ds))}</div>")
-                : default;
+
+            var deprecated = DeprecatedBadge(value.deprecated);
+            var deprecatedReason = DeprecatedReason(value.deprecated);
+            var titleHtml = deprecated is null ? Html($"{title}") : Html($"<span style='text-decoration: line-through'>{title}</span>");
 
             var src = string.IsNullOrEmpty(value.src)
                 ? default
                 : Html($" <a class='header-action link-secondary' title='View source' href='{value.src}'><i class='bi bi-code-slash'></i></a>");
 
-            return api.Value switch
+            return Html($"<h{level} class='section api' {attributes} id='{value.id}'>{titleHtml} {deprecated} {src}</h{level}> {deprecatedReason}");
+        }
+
+        HtmlTemplate? DeprecatedBadge(OneOf<bool, string>? value, string fontSize = ".5em")
+        {
+            var isDeprecated = value?.Value switch
             {
-                Api1 api1 => Html($"<h1 class='section api' {attributes} id='{value.id}'>{api1.api1}{deprecated}{src}</h1>{deprecatedReason}"),
-                Api2 api2 => Html($"<h2 class='section api' {attributes} id='{value.id}'>{api2.api2}{deprecated}{src}</h2>{deprecatedReason}"),
-                Api3 api3 => Html($"<h3 class='section api' {attributes} id='{value.id}'>{api3.api3}{deprecated}{src}</h3>{deprecatedReason}"),
-                Api4 api4 => Html($"<h4 class='section api' {attributes} id='{value.id}'>{api4.api4}{deprecated}{src}</h4>{deprecatedReason}"),
+                bool b when b => true,
+                string s => true,
+                _ => false,
             };
+
+            return isDeprecated ? Html($" <span class='badge rounded-pill text-bg-danger' style='font-size: {fontSize}; vertical-align: middle'>Deprecated</span>") : null;
+        }
+
+        HtmlTemplate DeprecatedReason(OneOf<bool, string>? value)
+        {
+            return value?.Value is string ds && !string.IsNullOrEmpty(ds)
+                ? Html($"\n<div class='alert alert-warning' role='alert'>{UnsafeHtml(markup(ds))}</div>")
+                : default;
         }
 
         HtmlTemplate Facts(Facts facts) => facts.facts.Length is 0 ? default : Html(
@@ -102,17 +117,25 @@ HtmlTemplate Code(Code code)
         HtmlTemplate Parameters(Parameters parameters) => parameters.parameters.Length is 0 ? default : Html(
             $"<dl class='parameters'>{parameters.parameters.Select(Parameter)}</dl>");
 
-        HtmlTemplate Parameter(Parameter parameter) => Html(
-            $"""
-            <dt>
-            {(string.IsNullOrEmpty(parameter.name) ? default
-                : string.IsNullOrEmpty(parameter.@default)
-                    ? Html($"<code>{parameter.name}</code>")
-                    : Html($"<code>{parameter.name} = {parameter.@default}</code>"))}
-            {Inline(parameter.type)}
-            </dt>
-            <dd>{(string.IsNullOrEmpty(parameter.description) ? default : UnsafeHtml(markup(parameter.description)))}</dd>
-            """);
+        HtmlTemplate Parameter(Parameter parameter)
+        {
+            var deprecated = DeprecatedBadge(parameter.deprecated, ".875em");
+            var lineThrough = deprecated is not null ? UnsafeHtml(" style='text-decoration: line-through'") : default;
+
+            var title = string.IsNullOrEmpty(parameter.name) ? default
+                    : string.IsNullOrEmpty(parameter.@default)
+                        ? Html($"<code{lineThrough}>{parameter.name}</code>")
+                        : Html($"<code{lineThrough}>{parameter.name} = {parameter.@default}</code>");
+
+            return Html(
+                $"""
+                <dt>{title} {Inline(parameter.type)} {deprecated}</dt>
+                <dd>
+                {DeprecatedReason(parameter.deprecated)}
+                {(string.IsNullOrEmpty(parameter.description) ? default : UnsafeHtml(markup(parameter.description)))}
+                </dd>
+                """);
+        }
 
         HtmlTemplate Inline(Inline? inline) => inline?.Value switch
         {

src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs

@@ -124,9 +124,7 @@ void Api(int level, string title, ISymbol symbol, Compilation compilation)
                 var git = source is null || source.Remote is null ? null
                     : new GitSource(source.Remote.Repo, source.Remote.Branch, source.Remote.Path, source.StartLine + 1);
                 var src = git is null ? null : options.SourceUrl?.Invoke(git) ?? GitUtility.GetSourceUrl(git);
-                var obsoleteAttribute = symbol.GetAttributes().FirstOrDefault(a => a.AttributeClass?.Name == "ObsoleteAttribute");
-                var deprecated = obsoleteAttribute is null ? null :
-                    obsoleteAttribute.ConstructorArguments.FirstOrDefault().Value is string reason && !string.IsNullOrEmpty(reason) ? (OneOf<bool, string>?)reason : true;
+                var deprecated = Deprecated(symbol);
 
                 body.Add(level switch
                 {
@@ -137,6 +135,13 @@ void Api(int level, string title, ISymbol symbol, Compilation compilation)
                 });
             }
 
+            OneOf<bool, string>? Deprecated(ISymbol symbol)
+            {
+                if (symbol.GetAttributes().FirstOrDefault(a => a.AttributeClass?.Name == "ObsoleteAttribute") is { } obsoleteAttribute)
+                    return obsoleteAttribute.ConstructorArguments.FirstOrDefault().Value is string reason && !string.IsNullOrEmpty(reason) ? (OneOf<bool, string>?)reason : true;
+                return null;
+            }
+
             void Namespace()
             {
                 var namespaceSymbols = symbols.Select(n => n.symbol).ToHashSet(SymbolEqualityComparer.Default);
@@ -579,8 +584,14 @@ void EnumFields(INamedTypeSymbol type)
 
                 Parameter ToParameter(IFieldSymbol item)
                 {
-                    var docs = Comment(item, compilation) is { } comment ? comment.Summary : null;
-                    return new() { name = item.Name, @default = $"{item.ConstantValue}", description = docs };
+                    var docs = Comment(item, compilation) is { } comment ? string.Join("\n\n", comment.Summary, comment.Remarks) : null;
+
+                    return new()
+                    {
+                        name = item.Name, @default = $"{item.ConstantValue}",
+                        deprecated = Deprecated(item),
+                        description = docs,
+                    };
                 }
             }
 

templates/modern/src/dotnet.scss

@@ -3,7 +3,7 @@
  * The .NET Foundation licenses this file to you under the MIT license.
  */
 
-body[data-yaml-mime="ManagedReference"], body[data-yaml-mime="ApiPage"] article {
+body[data-yaml-mime="ManagedReference"] article, body[data-yaml-mime="ApiPage"] article {
   h1[data-uid] {
     position: relative;
     padding-right: 1.6rem;
@@ -65,8 +65,13 @@ body[data-yaml-mime="ManagedReference"], body[data-yaml-mime="ApiPage"] article
   }
 
   dl.parameters {
-    >dt>code {
-      margin-right: .2em;
+    >dt {
+      margin: 1em 0;
+
+      &>code {
+        margin-right: .2em;
+        font-size: 1em;
+      }
     }
   }