Skip to content

Commit ab3c5a2

Browse files
PerthCharernPerthCharern
authored
Add XML comments to all protected and public members/classes. (#82)
- Add XML comments to all protected and public members/classes. - No more XML warnings are present. - Some enum renames and class moves. - No content or logic changes. (This partially addresses #16).
1 parent 5bb6a48 commit ab3c5a2

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

55 files changed

+561
-173
lines changed

‎src/Microsoft.OpenApi.Readers/OpenApiDiagnostic.cs

Lines changed: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -8,8 +8,14 @@
88

99
namespace Microsoft.OpenApi.Readers
1010
{
11+
/// <summary>
12+
/// Object containing all diagnostic information related to Open API parsing.
13+
/// </summary>
1114
public class OpenApiDiagnostic : IDiagnostic
1215
{
16+
/// <summary>
17+
/// List of all errors.
18+
/// </summary>
1319
public IList<OpenApiError> Errors { get; set; } = new List<OpenApiError>();
1420
}
1521
}

‎src/Microsoft.OpenApi.Readers/OpenApiError.cs

Lines changed: 20 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -7,26 +7,39 @@
77

88
namespace Microsoft.OpenApi.Readers
99
{
10+
/// <summary>
11+
/// Error related to reading Open API YAML/JSON.
12+
/// </summary>
1013
public class OpenApiError
1114
{
12-
private readonly string message;
13-
private readonly string pointer;
15+
private readonly string _message;
16+
private readonly string _pointer;
1417

18+
/// <summary>
19+
/// Initializes the <see cref="OpenApiError"/> class using the message and pointer from the given exception.
20+
/// </summary>
1521
public OpenApiError(OpenApiException exception)
1622
{
17-
message = exception.Message;
18-
pointer = exception.Pointer;
23+
_message = exception.Message;
24+
_pointer = exception.Pointer;
1925
}
2026

27+
/// <summary>
28+
/// Initializes the <see cref="OpenApiError"/> class.
29+
/// </summary>
2130
public OpenApiError(string pointer, string message)
2231
{
23-
this.pointer = pointer;
24-
this.message = message;
32+
this._pointer = pointer;
33+
this._message = message;
2534
}
2635

36+
/// <summary>
37+
/// Gets the string representation of <see cref="OpenApiError"/>.
38+
/// </summary>
39+
/// <returns></returns>
2740
public override string ToString()
2841
{
29-
return message + (!string.IsNullOrEmpty(pointer) ? " at " + pointer : "");
42+
return _message + (!string.IsNullOrEmpty(_pointer) ? " at " + _pointer : "");
3043
}
3144
}
3245
}

‎src/Microsoft.OpenApi.Readers/ParseNodes/RootNode.cs

Lines changed: 13 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -37,21 +37,31 @@ public MapNode GetMap()
3737
}
3838
}
3939

40+
/// <summary>
41+
/// Extensions for JSON pointers.
42+
/// </summary>
4043
public static class JsonPointerExtensions
4144
{
42-
public static YamlNode Find(this JsonPointer currentpointer, YamlNode sample)
45+
/// <summary>
46+
/// Finds the YAML node that corresponds to this JSON pointer based on the base YAML node.
47+
/// </summary>
48+
/// <param name="currentpointer"></param>
49+
/// <param name="baseYamlNode"></param>
50+
/// <returns></returns>
51+
public static YamlNode Find(this JsonPointer currentpointer, YamlNode baseYamlNode)
4352
{
4453
if (currentpointer.Tokens.Length == 0)
4554
{
46-
return sample;
55+
return baseYamlNode;
4756
}
4857

4958
try
5059
{
51-
var pointer = sample;
60+
var pointer = baseYamlNode;
5261
foreach (var token in currentpointer.Tokens)
5362
{
5463
var sequence = pointer as YamlSequenceNode;
64+
5565
if (sequence != null)
5666
{
5767
pointer = sequence.Children[Convert.ToInt32(token)];

‎src/Microsoft.OpenApi.Readers/ParsingContext.cs

Lines changed: 36 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -11,6 +11,9 @@
1111

1212
namespace Microsoft.OpenApi.Readers
1313
{
14+
/// <summary>
15+
/// Parsing context.
16+
/// </summary>
1417
public class ParsingContext
1518
{
1619
private readonly Stack<string> currentLocation = new Stack<string>();
@@ -23,24 +26,40 @@ public class ParsingContext
2326

2427
private readonly Dictionary<string, object> tempStorage = new Dictionary<string, object>();
2528

26-
public string Version { get; set; }
27-
29+
/// <summary>
30+
/// End the current object.
31+
/// </summary>
2832
public void EndObject()
2933
{
3034
currentLocation.Pop();
3135
}
3236

37+
/// <summary>
38+
/// Get the current location as string representing JSON pointer.
39+
/// </summary>
3340
public string GetLocation()
3441
{
3542
return "#/" + string.Join("/", currentLocation.Reverse().ToArray());
3643
}
3744

45+
/// <summary>
46+
/// Get the referenced object.
47+
/// </summary>
48+
/// <param name="diagnostic"></param>
49+
/// <param name="pointer"></param>
50+
/// <returns></returns>
3851
public IOpenApiReference GetReferencedObject(OpenApiDiagnostic diagnostic, string pointer)
3952
{
4053
var reference = _referenceService.FromString(pointer);
4154
return GetReferencedObject(diagnostic, reference);
4255
}
4356

57+
/// <summary>
58+
///
59+
/// </summary>
60+
/// <param name="diagnostic"></param>
61+
/// <param name="reference"></param>
62+
/// <returns></returns>
4463
public IOpenApiReference GetReferencedObject(OpenApiDiagnostic diagnostic, OpenApiReference reference)
4564
{
4665
IOpenApiReference returnValue = null;
@@ -72,27 +91,39 @@ public IOpenApiReference GetReferencedObject(OpenApiDiagnostic diagnostic, OpenA
7291
return returnValue;
7392
}
7493

75-
public T GetTempStorage<T>(string key) where T : class
94+
/// <summary>
95+
/// Gets the value from the temporary storage matching the given key.
96+
/// </summary>
97+
public T GetFromTempStorage<T>(string key) where T : class
7698
{
77-
object value;
78-
if (tempStorage.TryGetValue(key, out value))
99+
if (tempStorage.TryGetValue(key, out var value))
79100
{
80101
return (T)value;
81102
}
82103

83104
return null;
84105
}
85106

107+
/// <summary>
108+
/// Sets the reference service.
109+
/// </summary>
110+
/// <param name="referenceService"></param>
86111
public void SetReferenceService(IOpenApiReferenceService referenceService)
87112
{
88113
this._referenceService = referenceService;
89114
}
90115

116+
/// <summary>
117+
/// Sets the temporary storge for this key and value.
118+
/// </summary>
91119
public void SetTempStorage(string key, object value)
92120
{
93121
tempStorage[key] = value;
94122
}
95123

124+
/// <summary>
125+
/// Starts an object with the given object name.
126+
/// </summary>
96127
public void StartObject(string objectName)
97128
{
98129
currentLocation.Push(objectName);

‎src/Microsoft.OpenApi.Readers/V2/OpenApiDocumentDeserializer.cs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -65,9 +65,9 @@ internal static partial class OpenApiV2Deserializer
6565

6666
private static void MakeServers(IList<OpenApiServer> servers, ParsingContext context)
6767
{
68-
var host = context.GetTempStorage<string>("host");
69-
var basePath = context.GetTempStorage<string>("basePath");
70-
var schemes = context.GetTempStorage<List<string>>("schemes");
68+
var host = context.GetFromTempStorage<string>("host");
69+
var basePath = context.GetFromTempStorage<string>("basePath");
70+
var schemes = context.GetFromTempStorage<List<string>>("schemes");
7171

7272
if (schemes != null)
7373
{

‎src/Microsoft.OpenApi.Readers/V2/OpenApiHeaderDeserializer.cs

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -76,7 +76,7 @@ public static OpenApiHeader LoadHeader(ParseNode node)
7676
property.ParseField(header, HeaderFixedFields, HeaderPatternFields);
7777
}
7878

79-
var schema = node.Context.GetTempStorage<OpenApiSchema>("schema");
79+
var schema = node.Context.GetFromTempStorage<OpenApiSchema>("schema");
8080
if (schema != null)
8181
{
8282
header.Schema = schema;

‎src/Microsoft.OpenApi.Readers/V2/OpenApiOperationDeserializer.cs

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -103,14 +103,14 @@ internal static OpenApiOperation LoadOperation(ParseNode node)
103103
ParseMap(mapNode, operation, OperationFixedFields, OperationPatternFields);
104104

105105
// Build request body based on information determined while parsing OpenApiOperation
106-
var bodyParameter = node.Context.GetTempStorage<OpenApiParameter>("bodyParameter");
106+
var bodyParameter = node.Context.GetFromTempStorage<OpenApiParameter>("bodyParameter");
107107
if (bodyParameter != null)
108108
{
109109
operation.RequestBody = CreateRequestBody(node.Context, bodyParameter);
110110
}
111111
else
112112
{
113-
var formParameters = node.Context.GetTempStorage<List<OpenApiParameter>>("formParameters");
113+
var formParameters = node.Context.GetFromTempStorage<List<OpenApiParameter>>("formParameters");
114114
if (formParameters != null)
115115
{
116116
operation.RequestBody = CreateFormBody(formParameters);
@@ -162,8 +162,8 @@ private static OpenApiRequestBody CreateFormBody(List<OpenApiParameter> formPara
162162

163163
private static OpenApiRequestBody CreateRequestBody(ParsingContext context, OpenApiParameter bodyParameter)
164164
{
165-
var consumes = context.GetTempStorage<List<string>>("operationproduces") ??
166-
context.GetTempStorage<List<string>>("globalproduces") ?? new List<string> {"application/json"};
165+
var consumes = context.GetFromTempStorage<List<string>>("operationproduces") ??
166+
context.GetFromTempStorage<List<string>>("globalproduces") ?? new List<string> {"application/json"};
167167

168168
var requestBody = new OpenApiRequestBody
169169
{

‎src/Microsoft.OpenApi.Readers/V2/OpenApiParameterDeserializer.cs

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -199,7 +199,7 @@ private static void ProcessIn(OpenApiParameter o, ParseNode n)
199199
n.Context.SetTempStorage("bodyParameter", o);
200200
break;
201201
case "form":
202-
var formParameters = n.Context.GetTempStorage<List<OpenApiParameter>>("formParameters");
202+
var formParameters = n.Context.GetFromTempStorage<List<OpenApiParameter>>("formParameters");
203203
if (formParameters == null)
204204
{
205205
formParameters = new List<OpenApiParameter>();
@@ -227,7 +227,7 @@ public static OpenApiParameter LoadParameter(ParseNode node)
227227

228228
ParseMap(mapNode, parameter, ParameterFixedFields, ParameterPatternFields);
229229

230-
var schema = node.Context.GetTempStorage<OpenApiSchema>("schema");
230+
var schema = node.Context.GetFromTempStorage<OpenApiSchema>("schema");
231231
if (schema != null)
232232
{
233233
parameter.Schema = schema;

‎src/Microsoft.OpenApi.Readers/V2/OpenApiResponseDeserializer.cs

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -67,13 +67,13 @@ public static OpenApiResponse LoadResponse(ParseNode node)
6767

6868
private static void ProcessProduces(OpenApiResponse response, ParsingContext context)
6969
{
70-
var produces = context.GetTempStorage<List<string>>("operationproduces") ??
71-
context.GetTempStorage<List<string>>("globalproduces") ?? new List<string> {"application/json"};
70+
var produces = context.GetFromTempStorage<List<string>>("operationproduces") ??
71+
context.GetFromTempStorage<List<string>>("globalproduces") ?? new List<string> {"application/json"};
7272

7373
response.Content = new Dictionary<string, OpenApiMediaType>();
7474
foreach (var mt in produces)
7575
{
76-
var schema = context.GetTempStorage<OpenApiSchema>("operationschema");
76+
var schema = context.GetFromTempStorage<OpenApiSchema>("operationschema");
7777
OpenApiMediaType mediaType = null;
7878
if (schema != null)
7979
{

‎src/Microsoft.OpenApi/Any/AnyType.cs

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// ------------------------------------------------------------
2+
// Copyright (c) Microsoft Corporation. All rights reserved.
3+
// Licensed under the MIT License (MIT). See LICENSE in the repo root for license information.
4+
// ------------------------------------------------------------
5+
6+
using Microsoft.OpenApi.Any;
7+
8+
namespace Microsoft.OpenApi.Any
9+
{
10+
11+
/// <summary>
12+
/// Type of an <see cref="IOpenApiAny"/>
13+
/// </summary>
14+
public enum AnyType
15+
{
16+
/// <summary>
17+
/// Primitive.
18+
/// </summary>
19+
Primitive,
20+
21+
/// <summary>
22+
/// Null.
23+
/// </summary>
24+
Null,
25+
26+
/// <summary>
27+
/// Array.
28+
/// </summary>
29+
Array,
30+
31+
/// <summary>
32+
/// Object.
33+
/// </summary>
34+
Object
35+
}
36+
}

0 commit comments

Comments
 (0)