Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Properties - Value Tags. #19

Open
wants to merge 5 commits into
base: main
Choose a base branch
from
Open

Properties - Value Tags. #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
9337ff8
initial property-value code
Mar 13, 2023
f25cbe3
updated nugets
Mar 13, 2023
ae7b8a8
added missing reference to valueCmlElement in DocumentationBuilder.Build
Mar 13, 2023
adffb33
added solution items folder
Mar 13, 2023
827175e
Merge pull request #1 from gwynnPalmer/value-on-properties
gwynnPalmer Mar 13, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 10 additions & 0 deletions dotnet-document.sln
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,16 @@ Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DotnetDocument.Tests", "tes
EndProject
Project("{FAE04EC0-301F-11D3-BF4B-00C04F79EFBC}") = "DotnetDocument.Performance", "test\DotnetDocument.Performance\DotnetDocument.Performance.csproj", "{87C75476-E094-4BB6-9F90-2A0B099686E4}"
EndProject
Project("{2150E333-8FDC-42A3-9474-1A3956D46DE8}") = "SolutionItems", "SolutionItems", "{654CBDE5-28CE-4677-B902-35CD8BB6CD3E}"
ProjectSection(SolutionItems) = preProject
.editorconfig = .editorconfig
.gitignore = .gitignore
Directory.Build.props = Directory.Build.props
LICENSE = LICENSE
README.md = README.md
build\Version.props = build\Version.props
EndProjectSection
EndProject
Global
GlobalSection(SolutionConfigurationPlatforms) = preSolution
Debug|Any CPU = Debug|Any CPU
Expand Down
10 changes: 5 additions & 5 deletions src/DotnetDocument.Tools/DotnetDocument.Tools.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -22,18 +22,18 @@

<ItemGroup>
<PackageReference Include="Ben.Demystifier" Version="0.4.1" />
<PackageReference Include="Microsoft.Extensions.Configuration" Version="6.0.0" />
<PackageReference Include="Microsoft.Extensions.Configuration" Version="6.0.1" />
<PackageReference Include="Microsoft.Extensions.Configuration.Abstractions" Version="6.0.0" />
<PackageReference Include="Microsoft.Extensions.Configuration.Binder" Version="6.0.0" />
<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="6.0.0" />
<PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="6.0.0" />
<PackageReference Include="Microsoft.Extensions.Configuration.EnvironmentVariables" Version="6.0.1" />
<PackageReference Include="Microsoft.Extensions.DependencyInjection" Version="6.0.1" />
<PackageReference Include="Microsoft.Extensions.Logging" Version="6.0.0" />
<PackageReference Include="Microsoft.Extensions.Logging.Configuration" Version="6.0.0" />
<PackageReference Include="Microsoft.Extensions.Logging.Console" Version="6.0.0" />
<PackageReference Include="Microsoft.Extensions.Options.ConfigurationExtensions" Version="6.0.0" />
<PackageReference Include="OneOf" Version="3.0.205" />
<PackageReference Include="OneOf" Version="3.0.223" />
<PackageReference Include="Serilog.Extensions.Logging" Version="3.1.0" />
<PackageReference Include="Serilog.Sinks.Console" Version="4.0.1" />
<PackageReference Include="Serilog.Sinks.Console" Version="4.1.0" />
<PackageReference Include="System.CommandLine" Version="2.0.0-beta1.20574.7" />
<PackageReference Include="YamlDotNet.NetCore" Version="1.0.0" />
</ItemGroup>
Expand Down
44 changes: 44 additions & 0 deletions src/DotnetDocument/Configuration/DocumentationOptions.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -159,13 +159,57 @@ public class PropertyDocumentationOptions : MemberDocumentationOptionsBase
public SummaryDocumentationOptions Summary { get; init; } =
new($"{TemplateKeys.Accessors} the value of the {TemplateKeys.Name}");

/// <summary>
/// Gets or inits the value of the value
/// </summary>
public ValueDocumentationOptions Value { get; init; } = new($"The {TemplateKeys.Name}.");

/// <summary>
/// Gets the syntax kind
/// </summary>
/// <returns>The syntax kind</returns>
public override SyntaxKind GetSyntaxKind() => SyntaxKind.PropertyDeclaration;
}

/// <summary>
/// Class value documentation options
/// </summary>
public class ValueDocumentationOptions
{
/// <summary>
/// Initializes a new instance of the <see cref="ValueDocumentationOptions" /> class
/// </summary>
public ValueDocumentationOptions()
{
}

/// <summary>
/// Initializes a new instance of the <see cref="ValueDocumentationOptions" /> class
/// </summary>
/// <param name="template" >The template</param>
public ValueDocumentationOptions(string template) => Template = template;

/// <summary>
/// Gets or inits the value of the template
/// </summary>
public string Template { get; init; } = $"The {TemplateKeys.Name}.";

/// <summary>
/// Gets or inits the value of the new line
/// </summary>
public bool NewLine { get; init; } = false;

/// <summary>
/// Gets or inits the value of the enabled
/// </summary>
public bool Enabled { get; init; } = true;

/// <summary>
/// Gets or inits the value of the include comments
/// </summary>
public bool IncludeComments { get; init; } = false;
}

/// <summary>
/// The enum documentation options class
/// </summary>
Expand Down
6 changes: 3 additions & 3 deletions src/DotnetDocument/DotnetDocument.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,9 +2,9 @@

<ItemGroup>
<PackageReference Include="Ben.Demystifier" Version="0.4.1" />
<PackageReference Include="Humanizer" Version="2.13.14" />
<PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.0.1" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="6.0.0" />
<PackageReference Include="Humanizer" Version="2.14.1" />
<PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.5.0" />
<PackageReference Include="Microsoft.Extensions.Logging.Abstractions" Version="6.0.3" />
<PackageReference Include="Microsoft.Extensions.Options" Version="6.0.0" />
</ItemGroup>

Expand Down
16 changes: 13 additions & 3 deletions src/DotnetDocument/Strategies/PropertyDocumentationStrategy.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -90,10 +90,20 @@ public override PropertyDeclarationSyntax Apply(PropertyDeclarationSyntax node)
{
}

return GetDocumentationBuilder()
var builder = GetDocumentationBuilder()
.For(node)
.WithSummary(summary.ToArray())
.Build();
.WithSummary(summary.ToArray());

if (_options.Value.Enabled)
{
var value = _options.Value.Template
.Replace(TemplateKeys.Accessors, accessorsDescription)
.Replace(TemplateKeys.Name, humanizedPropertyName);

builder = builder.WithValue(value);
}

return builder.Build();
}
}
}
32 changes: 31 additions & 1 deletion src/DotnetDocument/Syntax/DocumentationBuilder.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -43,6 +43,11 @@ public class DocumentationBuilder<T> where T : SyntaxNode
/// </summary>
private bool _hasReturns;

/// <summary>
/// Gets the value of the has value
/// </summary>
private bool HasValue => !string.IsNullOrWhiteSpace(_value);

/// <summary>
/// The node
/// </summary>
Expand All @@ -53,6 +58,11 @@ public class DocumentationBuilder<T> where T : SyntaxNode
/// </summary>
private string? _returnsDescription;

/// <summary>
/// The value
/// </summary>
private string? _value;

/// <summary>
/// Fors the node
/// </summary>
Expand Down Expand Up @@ -219,6 +229,18 @@ public DocumentationBuilder<T> WithTypeParams(IEnumerable<(string name, string d
return this;
}

/// <summary>
/// Adds the value using the specified value
/// </summary>
/// <param name="value" >The value</param>
/// <returns>A documentation builder of t</returns>
public DocumentationBuilder<T> WithValue(string value)
{
_value = OnlyWhen.NotNull(value, nameof(value));

return this;
}

/// <summary>
/// Builds this instance
/// </summary>
Expand Down Expand Up @@ -270,14 +292,22 @@ public T Build()
// Declare the returns XML element
returnsXmlElement = DocumentationFactory.Returns(_returnsDescription ?? string.Empty);

XmlElementSyntax? valueXmlElement = null;
if (HasValue)
// Declare the value XML element
{
valueXmlElement = DocumentationFactory.Value(_value ?? string.Empty);
}

// Build the documentation trivia syntax for the entire doc
var docCommentTriviaSyntax = DocumentationFactory.XmlDocument(newLineXmlNode,
summaryXmlElement,
seeAlsoElements,
typeParamElements,
paramElements,
exceptionsElements,
returnsXmlElement);
returnsXmlElement,
valueXmlElement);

// Wrap the doc into a syntax trivia
var documentationTrivia = SyntaxFactory.Trivia(docCommentTriviaSyntax);
Expand Down
19 changes: 18 additions & 1 deletion src/DotnetDocument/Syntax/DocumentationFactory.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -156,6 +156,15 @@ public static XmlElementSyntax TypeParam(string type, string description)
.XmlElement(startTag, descriptionXml, endTag);
}

/// <summary>
/// Values the description
/// </summary>
/// <param name="description" >The description</param>
/// <returns>The xml element syntax</returns>
public static XmlElementSyntax Value(string description) => SyntaxFactory
.XmlValueElement(SyntaxFactory
.XmlText(description));

/// <summary>
/// Xmls the document using the specified xml indented new line
/// </summary>
Expand All @@ -166,6 +175,7 @@ public static XmlElementSyntax TypeParam(string type, string description)
/// <param name="parameters">The parameters</param>
/// <param name="exceptions">The exceptions</param>
/// <param name="returns">The returns</param>
/// <param name="value" >The value</param>
/// <returns>The documentation comment trivia syntax</returns>
public static DocumentationCommentTriviaSyntax XmlDocument(
XmlTextSyntax xmlIndentedNewLine,
Expand All @@ -174,7 +184,8 @@ public static DocumentationCommentTriviaSyntax XmlDocument(
List<XmlElementSyntax>? typeParameters = null,
List<XmlElementSyntax>? parameters = null,
List<XmlElementSyntax>? exceptions = null,
XmlElementSyntax? returns = null)
XmlElementSyntax? returns = null,
XmlElementSyntax? value = null)
{
var list = new List<XmlNodeSyntax>
{
Expand Down Expand Up @@ -215,6 +226,12 @@ public static DocumentationCommentTriviaSyntax XmlDocument(
list.Add(returns);
}

if (value is not null)
{
list.Add(xmlIndentedNewLine);
list.Add(value);
}

// This is the trivia syntax for the entire doc
return SyntaxFactory.DocumentationComment(list.ToArray());
}
Expand Down
9 changes: 9 additions & 0 deletions src/DotnetDocument/Utils/EnglishUtils.cs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,6 +15,15 @@ public static class EnglishUtils
/// <returns>The string</returns>
public static string ConjugateToThirdPersonSingular(string verb)
{
switch (verb)
{
case "be": return "is";
case "has": return verb;
case "have": return "has";
case "is": return verb;
}

// ss should be replaced by "es", s is debatable, but generally s => es should suffice.
// Check if verb ends with one of the following chars
if (verb.EndsWith("ch") || verb.EndsWith("s") || verb.EndsWith("sh") ||
verb.EndsWith("x") || verb.EndsWith("z") || verb.EndsWith("o"))
Expand Down
4 changes: 2 additions & 2 deletions test/DotnetDocument.Performance/DotnetDocument.Performance.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,8 +1,8 @@
<Project Sdk="Microsoft.NET.Sdk">

<ItemGroup>
<PackageReference Include="BenchmarkDotNet" Version="0.13.1" />
<PackageReference Include="BenchmarkDotNet.Annotations" Version="0.13.1" />
<PackageReference Include="BenchmarkDotNet" Version="0.13.5" />
<PackageReference Include="BenchmarkDotNet.Annotations" Version="0.13.5" />
</ItemGroup>

<ItemGroup>
Expand Down
18 changes: 9 additions & 9 deletions test/DotnetDocument.Tests/DotnetDocument.Tests.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,19 +5,19 @@
</PropertyGroup>

<ItemGroup>
<PackageReference Include="AutoFixture" Version="4.17.0" />
<PackageReference Include="AutoFixture.AutoMoq" Version="4.17.0" />
<PackageReference Include="Bogus" Version="34.0.1" />
<PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.0.1" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.0.0" />
<PackageReference Include="Shouldly" Version="4.0.3" />
<PackageReference Include="AutoFixture" Version="4.18.0" />
<PackageReference Include="AutoFixture.AutoMoq" Version="4.18.0" />
<PackageReference Include="Bogus" Version="34.0.2" />
<PackageReference Include="Microsoft.CodeAnalysis.CSharp" Version="4.5.0" />
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.5.0" />
<PackageReference Include="Shouldly" Version="4.1.0" />
<PackageReference Include="System.ComponentModel.TypeConverter" Version="4.3.0" />
<PackageReference Include="xunit" Version="2.4.1" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.4.3">
<PackageReference Include="xunit" Version="2.4.2" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.4.5">
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>
<PackageReference Include="coverlet.collector" Version="3.1.0">
<PackageReference Include="coverlet.collector" Version="3.2.0">
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>
Expand Down
8 changes: 4 additions & 4 deletions test/DotnetDocument.Tools.Tests/DotnetDocument.Tools.Tests.csproj
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5,13 +5,13 @@
</PropertyGroup>

<ItemGroup>
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.0.0" />
<PackageReference Include="xunit" Version="2.4.1" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.4.3">
<PackageReference Include="Microsoft.NET.Test.Sdk" Version="17.5.0" />
<PackageReference Include="xunit" Version="2.4.2" />
<PackageReference Include="xunit.runner.visualstudio" Version="2.4.5">
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>
<PackageReference Include="coverlet.collector" Version="3.1.0">
<PackageReference Include="coverlet.collector" Version="3.2.0">
<IncludeAssets>runtime; build; native; contentfiles; analyzers; buildtransitive</IncludeAssets>
<PrivateAssets>all</PrivateAssets>
</PackageReference>
Expand Down