Skip to content

Commit ea78da5

Browse files
yufeihyufeih
authored
Merge 70ff028 into 5082454 
2 parents 5082454 + 70ff028 commit ea78da5

File tree

4 files changed

+98
-31
lines changed

4 files changed

+98
-31
lines changed

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

Lines changed: 29 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -160,4 +160,33 @@ public void Issue1887() { }
160160
/// $$\left\{\begin{matrix}a, a<b \\ b, b>a\\ \end{matrix} \right.$$
161161
/// </summary>
162162
public static double Issue9216() => 0.0;
163+
164+
public enum Issue9260
165+
{
166+
/// <summary>
167+
/// This is a regular enum value.
168+
/// </summary>
169+
/// <remarks>
170+
/// This is a remarks section. Very important remarks about Value go here.
171+
/// </remarks>
172+
Value,
173+
174+
/// <summary>
175+
/// This is old and unused. You shouldn't use it anymore.
176+
/// </summary>
177+
/// <remarks>
178+
/// Don't use this, seriously! Use Value instead.
179+
/// </remarks>
180+
[Obsolete]
181+
OldAndUnusedValue,
182+
183+
/// <summary>
184+
/// This is old and unused. You shouldn't use it anymore.
185+
/// </summary>
186+
/// <remarks>
187+
/// Don't use this, seriously! Use Value instead.
188+
/// </remarks>
189+
[Obsolete("Use Value")]
190+
OldAndUnusedValue2,
191+
}
163192
}

‎src/Docfx.Build/ApiPage/ApiPageHtmlTemplate.cs‎

Lines changed: 47 additions & 24 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,7 @@
44
#if NET7_0_OR_GREATER
55

66
using System.Net;
7+
using OneOf;
78
using static Docfx.Build.HtmlTemplate;
89

910
#nullable enable
@@ -47,28 +48,42 @@ HtmlTemplate Api(Api api)
4748
? default
4849
: UnsafeHtml(string.Join(" ", value.metadata.Select(m => $"data-{WebUtility.HtmlEncode(m.Key)}='{WebUtility.HtmlEncode(m.Value)}'")));
4950

50-
var isDeprecated = value.deprecated?.Value switch
51+
var (level, title) = api.Value switch
5152
{
52-
bool b when b => true,
53-
string s => true,
54-
_ => false,
53+
Api1 a1 => (1, a1.api1),
54+
Api2 a2 => (2, a2.api2),
55+
Api3 a3 => (3, a3.api3),
56+
Api4 a4 => (4, a4.api4),
5557
};
56-
var deprecated = isDeprecated ? Html($" <span class='badge rounded-pill text-bg-danger' style='font-size: .5em; vertical-align: middle'>Deprecated</span>") : default;
57-
var deprecatedReason = value.deprecated?.Value is string ds && !string.IsNullOrEmpty(ds)
58-
? Html($"\n<div class='alert alert-warning' role='alert'>{UnsafeHtml(markup(ds))}</div>")
59-
: default;
58+
59+
var deprecated = DeprecatedBadge(value.deprecated);
60+
var deprecatedReason = DeprecatedReason(value.deprecated);
61+
var titleHtml = deprecated is null ? Html($"{title}") : Html($"<span style='text-decoration: line-through'>{title}</span>");
6062

6163
var src = string.IsNullOrEmpty(value.src)
6264
? default
6365
: Html($" <a class='header-action link-secondary' title='View source' href='{value.src}'><i class='bi bi-code-slash'></i></a>");
6466

65-
return api.Value switch
67+
return Html($"<h{level} class='section api' {attributes} id='{value.id}'>{titleHtml} {deprecated} {src}</h{level}> {deprecatedReason}");
68+
}
69+
70+
HtmlTemplate? DeprecatedBadge(OneOf<bool, string>? value, string fontSize = ".5em")
71+
{
72+
var isDeprecated = value?.Value switch
6673
{
67-
Api1 api1 => Html($"<h1 class='section api' {attributes} id='{value.id}'>{api1.api1}{deprecated}{src}</h1>{deprecatedReason}"),
68-
Api2 api2 => Html($"<h2 class='section api' {attributes} id='{value.id}'>{api2.api2}{deprecated}{src}</h2>{deprecatedReason}"),
69-
Api3 api3 => Html($"<h3 class='section api' {attributes} id='{value.id}'>{api3.api3}{deprecated}{src}</h3>{deprecatedReason}"),
70-
Api4 api4 => Html($"<h4 class='section api' {attributes} id='{value.id}'>{api4.api4}{deprecated}{src}</h4>{deprecatedReason}"),
74+
bool b when b => true,
75+
string s => true,
76+
_ => false,
7177
};
78+
79+
return isDeprecated ? Html($" <span class='badge rounded-pill text-bg-danger' style='font-size: {fontSize}; vertical-align: middle'>Deprecated</span>") : null;
80+
}
81+
82+
HtmlTemplate DeprecatedReason(OneOf<bool, string>? value)
83+
{
84+
return value?.Value is string ds && !string.IsNullOrEmpty(ds)
85+
? Html($"\n<div class='alert alert-warning' role='alert'>{UnsafeHtml(markup(ds))}</div>")
86+
: default;
7287
}
7388

7489
HtmlTemplate Facts(Facts facts) => facts.facts.Length is 0 ? default : Html(
@@ -102,17 +117,25 @@ HtmlTemplate Code(Code code)
102117
HtmlTemplate Parameters(Parameters parameters) => parameters.parameters.Length is 0 ? default : Html(
103118
$"<dl class='parameters'>{parameters.parameters.Select(Parameter)}</dl>");
104119

105-
HtmlTemplate Parameter(Parameter parameter) => Html(
106-
$"""
107-
<dt>
108-
{(string.IsNullOrEmpty(parameter.name) ? default
109-
: string.IsNullOrEmpty(parameter.@default)
110-
? Html($"<code>{parameter.name}</code>")
111-
: Html($"<code>{parameter.name} = {parameter.@default}</code>"))}
112-
{Inline(parameter.type)}
113-
</dt>
114-
<dd>{(string.IsNullOrEmpty(parameter.description) ? default : UnsafeHtml(markup(parameter.description)))}</dd>
115-
""");
120+
HtmlTemplate Parameter(Parameter parameter)
121+
{
122+
var deprecated = DeprecatedBadge(parameter.deprecated, ".9em");
123+
var lineThrough = deprecated is not null ? UnsafeHtml(" style='text-decoration: line-through'") : default;
124+
125+
var title = string.IsNullOrEmpty(parameter.name) ? default
126+
: string.IsNullOrEmpty(parameter.@default)
127+
? Html($"<code{lineThrough}>{parameter.name}</code>")
128+
: Html($"<code{lineThrough}>{parameter.name} = {parameter.@default}</code>");
129+
130+
return Html(
131+
$"""
132+
<dt>{title} {Inline(parameter.type)} {deprecated}</dt>
133+
<dd>
134+
{DeprecatedReason(parameter.deprecated)}
135+
{(string.IsNullOrEmpty(parameter.description) ? default : UnsafeHtml(markup(parameter.description)))}
136+
</dd>
137+
""");
138+
}
116139

117140
HtmlTemplate Inline(Inline? inline) => inline?.Value switch
118141
{

‎src/Docfx.Dotnet/DotnetApiCatalog.ApiPage.cs‎

Lines changed: 16 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -124,9 +124,7 @@ void Api(int level, string title, ISymbol symbol, Compilation compilation)
124124
var git = source is null || source.Remote is null ? null
125125
: new GitSource(source.Remote.Repo, source.Remote.Branch, source.Remote.Path, source.StartLine + 1);
126126
var src = git is null ? null : options.SourceUrl?.Invoke(git) ?? GitUtility.GetSourceUrl(git);
127-
var obsoleteAttribute = symbol.GetAttributes().FirstOrDefault(a => a.AttributeClass?.Name == "ObsoleteAttribute");
128-
var deprecated = obsoleteAttribute is null ? null :
129-
obsoleteAttribute.ConstructorArguments.FirstOrDefault().Value is string reason && !string.IsNullOrEmpty(reason) ? (OneOf<bool, string>?)reason : true;
127+
var deprecated = Deprecated(symbol);
130128

131129
body.Add(level switch
132130
{
@@ -137,6 +135,13 @@ void Api(int level, string title, ISymbol symbol, Compilation compilation)
137135
});
138136
}
139137

138+
OneOf<bool, string>? Deprecated(ISymbol symbol)
139+
{
140+
if (symbol.GetAttributes().FirstOrDefault(a => a.AttributeClass?.Name == "ObsoleteAttribute") is { } obsoleteAttribute)
141+
return obsoleteAttribute.ConstructorArguments.FirstOrDefault().Value is string reason && !string.IsNullOrEmpty(reason) ? (OneOf<bool, string>?)reason : true;
142+
return null;
143+
}
144+
140145
void Namespace()
141146
{
142147
var namespaceSymbols = symbols.Select(n => n.symbol).ToHashSet(SymbolEqualityComparer.Default);
@@ -579,8 +584,14 @@ void EnumFields(INamedTypeSymbol type)
579584

580585
Parameter ToParameter(IFieldSymbol item)
581586
{
582-
var docs = Comment(item, compilation) is { } comment ? comment.Summary : null;
583-
return new() { name = item.Name, @default = $"{item.ConstantValue}", description = docs };
587+
var docs = Comment(item, compilation) is { } comment ? string.Join("\n\n", comment.Summary, comment.Remarks) : null;
588+
589+
return new()
590+
{
591+
name = item.Name, @default = $"{item.ConstantValue}",
592+
deprecated = Deprecated(item),
593+
description = docs,
594+
};
584595
}
585596
}
586597

‎templates/modern/src/dotnet.scss‎

Lines changed: 6 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -65,8 +65,12 @@ body[data-yaml-mime="ManagedReference"], body[data-yaml-mime="ApiPage"] article
6565
}
6666

6767
dl.parameters {
68-
>dt>code {
69-
margin-right: .2em;
68+
>dt {
69+
margin: 1em 0;
70+
&>code {
71+
margin-right: .2em;
72+
font-size: 1em;
73+
}
7074
}
7175
}
7276

0 commit comments

Comments
 (0)