From 54fc967f7eb884692a09f31be3dd877309eb6f11 Mon Sep 17 00:00:00 2001 From: Russ Cam Date: Sat, 17 Dec 2016 00:15:48 +1100 Subject: [PATCH] Add important admonition about using System.Decimal POCO property types (#2495) Bump AsciiDoctNet to support additional asciidoc syntax Closes #2463 Conflicts: src/Tests/ClientConcepts/HighLevel/Mapping/AutoMap.doc.cs --- .../high-level/mapping/auto-map.asciidoc | 23 ++++++++++++++++++ docs/high-level.asciidoc | 3 +++ docs/low-level.asciidoc | 1 + paket.lock | 2 +- .../AsciiDoc/GeneratedAsciidocVisitor.cs | 4 ++-- .../Files/CSharpDocumentationFile.cs | 1 - .../Documentation/Files/DocumentationFile.cs | 3 --- .../Files/ImageDocumentationFile.cs | 2 +- .../HighLevel/Mapping/AutoMap.doc.cs | 24 ++++++++++++++++++- 9 files changed, 54 insertions(+), 9 deletions(-) diff --git a/docs/client-concepts/high-level/mapping/auto-map.asciidoc b/docs/client-concepts/high-level/mapping/auto-map.asciidoc index deff4c9f3da..5d4188306f4 100644 --- a/docs/client-concepts/high-level/mapping/auto-map.asciidoc +++ b/docs/client-concepts/high-level/mapping/auto-map.asciidoc @@ -290,6 +290,29 @@ var expected = new Expect(expected).WhenSerializing((ICreateIndexRequest)descriptor); ---- +[IMPORTANT] +==== +Some .NET types do not have direct equivalent Elasticsearch types. For example, `System.Decimal` is a type +commonly used to express currencies and other financial calculations that require large numbers of significant +integral and fractional digits and no round-off errors. There is no equivalent type in Elasticsearch, and the +nearest type is {ref_current}/number.html[``double``], a double-precision 64-bit IEEE 754 floating point. + +When a POCO has a `System.Decimal` property, it is automapped to the Elasticsearch `double` type. With the caveat +of a potential loss of precision, this is generally acceptable for a lot of use cases, but it can however cause +problems in _some_ edge cases. + +As the https://download.microsoft.com/download/3/8/8/388e7205-bc10-4226-b2a8-75351c669b09/csharp%20language%20specification.doc[C# Specification states], + +[quote, C# Specification section 6.2.1] +For a conversion from `decimal` to `float` or `double`, the `decimal` value is rounded to the nearest `double` or `float` value. +While this conversion may lose precision, it never causes an exception to be thrown. + +This conversion causes an exception to be thrown at deserialization time for `Decimal.MinValue` and `Decimal.MaxValue` because, at +serialization time, the nearest `double` value that is converted to is outside of the bounds of `Decimal.MinValue` or `Decimal.MaxValue`, +respectively. In these cases, it is advisable to use `double` as the POCO property type. + +==== + [[auto-mapping-with-overrides]] [float] == Auto mapping with overrides diff --git a/docs/high-level.asciidoc b/docs/high-level.asciidoc index da504f53efc..be22f347ce9 100644 --- a/docs/high-level.asciidoc +++ b/docs/high-level.asciidoc @@ -14,6 +14,7 @@ please modify the original csharp file found at the link and submit the PR with [partintro] -- The high level client, `ElasticClient`, provides a strongly typed query DSL that maps one-to-one with the Elasticsearch query DSL. + It can be installed from the Package Manager Console inside Visual Studio using [source,shell] @@ -22,8 +23,10 @@ Install-Package NEST ---- Or by searching for https://www.nuget.org/packages/NEST[NEST] in the Package Manager GUI. + NEST internally uses and still exposes the low level client, `ElasticLowLevelClient`, from <> via the `.LowLevel` property on `ElasticClient`. + There are a number of conventions that NEST uses for inference of * <> diff --git a/docs/low-level.asciidoc b/docs/low-level.asciidoc index 49333f42f7d..f530bb942e0 100644 --- a/docs/low-level.asciidoc +++ b/docs/low-level.asciidoc @@ -15,6 +15,7 @@ please modify the original csharp file found at the link and submit the PR with -- The low level client, `ElasticLowLevelClient`, is a low level, dependency free client that has no opinions about how you build and represent your requests and responses. + It can be installed from the Package Manager Console inside Visual Studio using [source,shell] diff --git a/paket.lock b/paket.lock index 301e104d7aa..368bf5f427c 100644 --- a/paket.lock +++ b/paket.lock @@ -1,6 +1,6 @@ NUGET remote: https://www.nuget.org/api/v2 - AsciiDocNet (1.0.0-alpha3) + AsciiDocNet (1.0.0-alpha5) Bogus (7.1.6) NETStandard.Library (>= 1.6) - framework: >= netstandard13 Newtonsoft.Json (>= 9.0.1) - framework: >= net40, >= netstandard13 diff --git a/src/CodeGeneration/DocGenerator/AsciiDoc/GeneratedAsciidocVisitor.cs b/src/CodeGeneration/DocGenerator/AsciiDoc/GeneratedAsciidocVisitor.cs index a816fb598ef..e4a1dc9fa59 100644 --- a/src/CodeGeneration/DocGenerator/AsciiDoc/GeneratedAsciidocVisitor.cs +++ b/src/CodeGeneration/DocGenerator/AsciiDoc/GeneratedAsciidocVisitor.cs @@ -264,7 +264,7 @@ public override void Visit(SectionTitle sectionTitle) var builder = new StringBuilder(); using (var writer = new AsciiDocVisitor(new StringWriter(builder))) { - writer.Visit(sectionTitle.Elements); + writer.Visit((InlineContainer)sectionTitle); } var title = builder.ToString().PascalToHyphen(); @@ -300,7 +300,7 @@ private bool LastSectionTitleMatches(Func predicate) var builder = new StringBuilder(); using (var visitor = new AsciiDocVisitor(new StringWriter(builder))) { - visitor.Visit(lastSectionTitle.Elements); + visitor.Visit((InlineContainer)lastSectionTitle); } return predicate(builder.ToString()); diff --git a/src/CodeGeneration/DocGenerator/Documentation/Files/CSharpDocumentationFile.cs b/src/CodeGeneration/DocGenerator/Documentation/Files/CSharpDocumentationFile.cs index 1448f24bd24..87a5934fecb 100644 --- a/src/CodeGeneration/DocGenerator/Documentation/Files/CSharpDocumentationFile.cs +++ b/src/CodeGeneration/DocGenerator/Documentation/Files/CSharpDocumentationFile.cs @@ -200,7 +200,6 @@ private void CleanDocumentAndWriteToFile(string body, FileInfo destination) document.Accept(new AsciiDocVisitor(file)); } - } } } diff --git a/src/CodeGeneration/DocGenerator/Documentation/Files/DocumentationFile.cs b/src/CodeGeneration/DocGenerator/Documentation/Files/DocumentationFile.cs index 2f7cedd3527..b79987f50c7 100644 --- a/src/CodeGeneration/DocGenerator/Documentation/Files/DocumentationFile.cs +++ b/src/CodeGeneration/DocGenerator/Documentation/Files/DocumentationFile.cs @@ -1,9 +1,6 @@ using System; -using System.Collections.Generic; using System.IO; -using System.Reflection.Emit; using System.Text.RegularExpressions; -using DocGenerator; namespace DocGenerator.Documentation.Files { diff --git a/src/CodeGeneration/DocGenerator/Documentation/Files/ImageDocumentationFile.cs b/src/CodeGeneration/DocGenerator/Documentation/Files/ImageDocumentationFile.cs index 75e79e5380a..a6e4b72e790 100644 --- a/src/CodeGeneration/DocGenerator/Documentation/Files/ImageDocumentationFile.cs +++ b/src/CodeGeneration/DocGenerator/Documentation/Files/ImageDocumentationFile.cs @@ -11,7 +11,7 @@ public override void SaveToDocumentationFolder() { var docFileName = this.CreateDocumentationLocation(); - // copy for asciidoc to work (path is relative to file) + // copy for asciidoc to work when viewing a single asciidoc in the browser (path is relative to file) this.FileLocation.CopyTo(docFileName.FullName, true); // copy to the root as well, for the doc generation process (path is relative to root) diff --git a/src/Tests/ClientConcepts/HighLevel/Mapping/AutoMap.doc.cs b/src/Tests/ClientConcepts/HighLevel/Mapping/AutoMap.doc.cs index c7f7f306a43..9958f34f128 100644 --- a/src/Tests/ClientConcepts/HighLevel/Mapping/AutoMap.doc.cs +++ b/src/Tests/ClientConcepts/HighLevel/Mapping/AutoMap.doc.cs @@ -275,6 +275,28 @@ public void UsingAutoMap() Expect(expected).WhenSerializing((ICreateIndexRequest)descriptor); } + /**[IMPORTANT] + * ==== + * Some .NET types do not have direct equivalent Elasticsearch types. For example, `System.Decimal` is a type + * commonly used to express currencies and other financial calculations that require large numbers of significant + * integral and fractional digits and no round-off errors. There is no equivalent type in Elasticsearch, and the + * nearest type is {ref_current}/number.html[``double``], a double-precision 64-bit IEEE 754 floating point. + * + * When a POCO has a `System.Decimal` property, it is automapped to the Elasticsearch `double` type. With the caveat + * of a potential loss of precision, this is generally acceptable for a lot of use cases, but it can however cause + * problems in _some_ edge cases. + * + * As the https://download.microsoft.com/download/3/8/8/388e7205-bc10-4226-b2a8-75351c669b09/csharp%20language%20specification.doc[C# Specification states], + * + * [quote, C# Specification section 6.2.1] + * For a conversion from `decimal` to `float` or `double`, the `decimal` value is rounded to the nearest `double` or `float` value. + * While this conversion may lose precision, it never causes an exception to be thrown. + * + * This conversion causes an exception to be thrown at deserialization time for `Decimal.MinValue` and `Decimal.MaxValue` because, at + * serialization time, the nearest `double` value that is converted to is outside of the bounds of `Decimal.MinValue` or `Decimal.MaxValue`, + * respectively. In these cases, it is advisable to use `double` as the POCO property type. + * ==== + */ /**[float] * == Auto mapping with overrides @@ -969,7 +991,7 @@ public void PutMappingAlsoAdheresToMaxRecursion() //endhide /**[float] - * == Applying conventions through the Visitor pattern + * == Applying conventions through the Visitor pattern * It is also possible to apply a transformation on all or specific properties. * * `.AutoMap()` internally implements the https://en.wikipedia.org/wiki/Visitor_pattern[visitor pattern]. The default visitor, `NoopPropertyVisitor`,