Skip to content

Commit 1c63d12

Browse files
carlossanlopcarlossanlop
committed
Clean the Docs APIs.
1 parent cccca92 commit 1c63d12

14 files changed

+113
-729
lines changed

‎src/PortToTripleSlash/src/libraries/Docs/DocsAPI.cs‎

Lines changed: 23 additions & 200 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,6 @@ internal abstract class DocsAPI : IDocsAPI
3232
Params.Any(p => p.Value.IsDocsEmpty()) ||
3333
TypeParams.Any(tp => tp.Value.IsDocsEmpty());
3434

35-
public abstract bool Changed { get; set; }
3635
public string FilePath { get; set; } = string.Empty;
3736

3837
public string DocId => _docId ??= GetApiSignatureDocId();
@@ -49,14 +48,7 @@ public List<DocsParameter> Parameters
4948
if (_parameters == null)
5049
{
5150
XElement? xeParameters = XERoot.Element("Parameters");
52-
if (xeParameters == null)
53-
{
54-
_parameters = new();
55-
}
56-
else
57-
{
58-
_parameters = xeParameters.Elements("Parameter").Select(x => new DocsParameter(x)).ToList();
59-
}
51+
_parameters = xeParameters == null ? (List<DocsParameter>)new() : xeParameters.Elements("Parameter").Select(x => new DocsParameter(x)).ToList();
6052
}
6153
return _parameters;
6254
}
@@ -72,222 +64,59 @@ public List<DocsTypeParameter> TypeParameters
7264
if (_typeParameters == null)
7365
{
7466
XElement? xeTypeParameters = XERoot.Element("TypeParameters");
75-
if (xeTypeParameters == null)
76-
{
77-
_typeParameters = new();
78-
}
79-
else
80-
{
81-
_typeParameters = xeTypeParameters.Elements("TypeParameter").Select(x => new DocsTypeParameter(x)).ToList();
82-
}
67+
_typeParameters = xeTypeParameters == null ? (List<DocsTypeParameter>)new() : xeTypeParameters.Elements("TypeParameter").Select(x => new DocsTypeParameter(x)).ToList();
8368
}
8469
return _typeParameters;
8570
}
8671
}
8772

88-
public XElement Docs
89-
{
90-
get
91-
{
92-
return XERoot.Element("Docs") ?? throw new NullReferenceException($"Docs section was null in {FilePath}");
93-
}
94-
}
73+
public XElement Docs => XERoot.Element("Docs") ?? throw new NullReferenceException($"Docs section was null in {FilePath}");
9574

9675
/// <summary>
9776
/// The param elements found inside the Docs section.
9877
/// </summary>
99-
public List<DocsParam> Params
100-
{
101-
get
102-
{
103-
if (_params == null)
104-
{
105-
if (Docs != null)
106-
{
107-
_params = Docs.Elements("param").Select(x => new DocsParam(this, x)).ToList();
108-
}
109-
else
110-
{
111-
_params = new List<DocsParam>();
112-
}
113-
}
114-
return _params;
115-
}
116-
}
78+
public List<DocsParam> Params => _params ??= Docs != null ? Docs.Elements("param").Select(x => new DocsParam(this, x)).ToList() : new List<DocsParam>();
11779

11880
/// <summary>
11981
/// The typeparam elements found inside the Docs section.
12082
/// </summary>
121-
public List<DocsTypeParam> TypeParams
122-
{
123-
get
124-
{
125-
if (_typeParams == null)
126-
{
127-
if (Docs != null)
128-
{
129-
_typeParams = Docs.Elements("typeparam").Select(x => new DocsTypeParam(this, x)).ToList();
130-
}
131-
else
132-
{
133-
_typeParams = new();
134-
}
135-
}
136-
return _typeParams;
137-
}
138-
}
83+
public List<DocsTypeParam> TypeParams => _typeParams ??= Docs != null ? Docs.Elements("typeparam").Select(x => new DocsTypeParam(this, x)).ToList() : (List<DocsTypeParam>)new();
13984

140-
public List<string> SeeAlsoCrefs
141-
{
142-
get
143-
{
144-
if (_seeAlsoCrefs == null)
145-
{
146-
if (Docs != null)
147-
{
148-
_seeAlsoCrefs = Docs.Elements("seealso").Select(x => XmlHelper.GetAttributeValue(x, "cref").DocIdEscaped()).ToList();
149-
}
150-
else
151-
{
152-
_seeAlsoCrefs = new();
153-
}
154-
}
155-
return _seeAlsoCrefs;
156-
}
157-
}
85+
public List<string> SeeAlsoCrefs => _seeAlsoCrefs ??= Docs != null ? Docs.Elements("seealso").Select(x => XmlHelper.GetAttributeValue(x, "cref").DocIdEscaped()).ToList() : (List<string>)new();
15886

159-
public List<string> AltMembers
160-
{
161-
get
162-
{
163-
if (_altMemberCrefs == null)
164-
{
165-
if (Docs != null)
166-
{
167-
_altMemberCrefs = Docs.Elements("altmember").Select(x => XmlHelper.GetAttributeValue(x, "cref").DocIdEscaped()).ToList();
168-
}
169-
else
170-
{
171-
_altMemberCrefs = new();
172-
}
173-
}
174-
return _altMemberCrefs;
175-
}
176-
}
87+
public List<string> AltMembers => _altMemberCrefs ??= Docs != null ? Docs.Elements("altmember").Select(x => XmlHelper.GetAttributeValue(x, "cref").DocIdEscaped()).ToList() : (List<string>)new();
17788

178-
public List<DocsRelated> Relateds
179-
{
180-
get
181-
{
182-
if (_relateds == null)
183-
{
184-
if (Docs != null)
185-
{
186-
_relateds = Docs.Elements("related").Select(x => new DocsRelated(this, x)).ToList();
187-
}
188-
else
189-
{
190-
_relateds = new();
191-
}
192-
}
193-
return _relateds;
194-
}
195-
}
89+
public List<DocsRelated> Relateds => _relateds ??= Docs != null ? Docs.Elements("related").Select(x => new DocsRelated(this, x)).ToList() : (List<DocsRelated>)new();
90+
91+
public abstract string Summary { get; }
92+
93+
public abstract string Value { get; }
19694

197-
public abstract string Summary { get; set; }
198-
public abstract string Value { get; set; }
19995
public abstract string ReturnType { get; }
200-
public abstract string Returns { get; set; }
201-
public abstract string Remarks { get; set; }
20296

203-
public abstract List<DocsException> Exceptions { get; }
97+
public abstract string Returns { get; }
20498

205-
public List<DocsAssemblyInfo> AssemblyInfos
206-
{
207-
get
208-
{
209-
if (_assemblyInfos == null)
210-
{
211-
_assemblyInfos = new List<DocsAssemblyInfo>();
212-
}
213-
return _assemblyInfos;
214-
}
215-
}
99+
public abstract string Remarks { get; }
216100

217-
public DocsParam SaveParam(XElement xeIntelliSenseXmlParam)
218-
{
219-
XElement xeDocsParam = new XElement(xeIntelliSenseXmlParam.Name);
220-
xeDocsParam.ReplaceAttributes(xeIntelliSenseXmlParam.Attributes());
221-
XmlHelper.SaveFormattedAsXml(xeDocsParam, xeIntelliSenseXmlParam.Value);
222-
DocsParam docsParam = new DocsParam(this, xeDocsParam);
223-
Changed = true;
224-
return docsParam;
225-
}
101+
public abstract List<DocsException> Exceptions { get; }
226102

227-
public APIKind Kind
228-
{
229-
get
230-
{
231-
return this switch
232-
{
233-
DocsMember _ => APIKind.Member,
234-
DocsType _ => APIKind.Type,
235-
_ => throw new ArgumentException("Unrecognized IDocsAPI object")
236-
};
237-
}
238-
}
103+
public List<DocsAssemblyInfo> AssemblyInfos => _assemblyInfos ??= new List<DocsAssemblyInfo>();
239104

240-
public DocsTypeParam AddTypeParam(string name, string value)
105+
public APIKind Kind => this switch
241106
{
242-
XElement typeParam = new XElement("typeparam");
243-
typeParam.SetAttributeValue("name", name);
244-
XmlHelper.AddChildFormattedAsXml(Docs, typeParam, value);
245-
Changed = true;
246-
return new DocsTypeParam(this, typeParam);
247-
}
107+
DocsMember _ => APIKind.Member,
108+
DocsType _ => APIKind.Type,
109+
_ => throw new ArgumentException("Unrecognized IDocsAPI object")
110+
};
248111

249112
// For Types, these elements are called TypeSignature.
250113
// For Members, these elements are called MemberSignature.
251114
protected abstract string GetApiSignatureDocId();
252115

253-
protected string GetNodesInPlainText(string name)
254-
{
255-
if (TryGetElement(name, addIfMissing: false, out XElement? element))
256-
{
257-
if (name == "remarks")
258-
{
259-
XElement? formatElement = element.Element("format");
260-
if (formatElement != null)
261-
{
262-
element = formatElement;
263-
}
264-
}
265-
266-
return XmlHelper.GetNodesInPlainText(element);
267-
}
268-
return string.Empty;
269-
}
270-
271-
protected void SaveFormattedAsXml(string name, string value, bool addIfMissing)
272-
{
273-
if (TryGetElement(name, addIfMissing, out XElement? element))
274-
{
275-
XmlHelper.SaveFormattedAsXml(element, value);
276-
Changed = true;
277-
}
278-
}
279-
280-
protected void SaveFormattedAsMarkdown(string name, string value, bool addIfMissing, bool isMember)
281-
{
282-
if (TryGetElement(name, addIfMissing, out XElement? element))
283-
{
284-
XmlHelper.SaveFormattedAsMarkdown(element, value, isMember);
285-
Changed = true;
286-
}
287-
}
116+
protected string GetNodesInPlainText(string name) => TryGetElement(name, out XElement? element) ? XmlHelper.GetNodesInPlainText(name, element) : string.Empty;
288117

289118
// Returns true if the element existed or had to be created with "To be added." as value. Returns false the element was not found and a new one was not created.
290-
private bool TryGetElement(string name, bool addIfMissing, [NotNullWhen(returnValue: true)] out XElement? element)
119+
private bool TryGetElement(string name, [NotNullWhen(returnValue: true)] out XElement? element)
291120
{
292121
element = null;
293122

@@ -298,12 +127,6 @@ private bool TryGetElement(string name, bool addIfMissing, [NotNullWhen(returnVa
298127

299128
element = Docs.Element(name);
300129

301-
if (element == null && addIfMissing)
302-
{
303-
element = new XElement(name);
304-
XmlHelper.AddChildFormattedAsXml(Docs, element, Configuration.ToBeAdded);
305-
}
306-
307130
return element != null;
308131
}
309132
}

‎src/PortToTripleSlash/src/libraries/Docs/DocsAssemblyInfo.cs‎

Lines changed: 5 additions & 23 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Licensed to the .NET Foundation under one or more agreements.
1+
// Licensed to the .NET Foundation under one or more agreements.
22
// The .NET Foundation licenses this file to you under the MIT license.
33

44
using System.Collections.Generic;
@@ -10,31 +10,13 @@ namespace ApiDocsSync.PortToTripleSlash.Docs
1010
internal class DocsAssemblyInfo
1111
{
1212
private readonly XElement XEAssemblyInfo;
13-
public string AssemblyName
14-
{
15-
get
16-
{
17-
return XmlHelper.GetChildElementValue(XEAssemblyInfo, "AssemblyName");
18-
}
19-
}
13+
14+
public string AssemblyName => XmlHelper.GetChildElementValue(XEAssemblyInfo, "AssemblyName");
2015

2116
private List<string>? _assemblyVersions;
22-
public List<string> AssemblyVersions
23-
{
24-
get
25-
{
26-
if (_assemblyVersions == null)
27-
{
28-
_assemblyVersions = XEAssemblyInfo.Elements("AssemblyVersion").Select(x => XmlHelper.GetNodesInPlainText(x)).ToList();
29-
}
30-
return _assemblyVersions;
31-
}
32-
}
17+
public List<string> AssemblyVersions => _assemblyVersions ??= XEAssemblyInfo.Elements("AssemblyVersion").Select(x => XmlHelper.GetNodesInPlainText("AssemblyVersion", x)).ToList();
3318

34-
public DocsAssemblyInfo(XElement xeAssemblyInfo)
35-
{
36-
XEAssemblyInfo = xeAssemblyInfo;
37-
}
19+
public DocsAssemblyInfo(XElement xeAssemblyInfo) => XEAssemblyInfo = xeAssemblyInfo;
3820

3921
public override string ToString() => AssemblyName;
4022
}

‎src/PortToTripleSlash/src/libraries/Docs/DocsAttribute.cs‎

Lines changed: 5 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
1-
// Licensed to the .NET Foundation under one or more agreements.
1+
// Licensed to the .NET Foundation under one or more agreements.
22
// The .NET Foundation licenses this file to you under the MIT license.
33

44
using System.Xml.Linq;
@@ -9,24 +9,10 @@ internal class DocsAttribute
99
{
1010
private readonly XElement XEAttribute;
1111

12-
public string FrameworkAlternate
13-
{
14-
get
15-
{
16-
return XmlHelper.GetAttributeValue(XEAttribute, "FrameworkAlternate");
17-
}
18-
}
19-
public string AttributeName
20-
{
21-
get
22-
{
23-
return XmlHelper.GetChildElementValue(XEAttribute, "AttributeName");
24-
}
25-
}
12+
public string FrameworkAlternate => XmlHelper.GetAttributeValue(XEAttribute, "FrameworkAlternate");
2613

27-
public DocsAttribute(XElement xeAttribute)
28-
{
29-
XEAttribute = xeAttribute;
30-
}
14+
public string AttributeName => XmlHelper.GetChildElementValue(XEAttribute, "AttributeName");
15+
16+
public DocsAttribute(XElement xeAttribute) => XEAttribute = xeAttribute;
3117
}
3218
}

0 commit comments

Comments
 (0)