This is an automated email from the ASF dual-hosted git repository.
dkulp pushed a commit to branch master
in repository https://gitbox.apache.org/repos/asf/avro.git
The following commit(s) were added to refs/heads/master by this push:
new 915cb45 AVRO-2155: Include documentation for named schemas in
generated code (#296)
915cb45 is described below
commit 915cb4541fa0e7d3d96646947f449cbb4b75589a
Author: Brian Lachniet <[email protected]>
AuthorDate: Wed Dec 5 09:52:38 2018 -0500
AVRO-2155: Include documentation for named schemas in generated code (#296)
* AVRO-2155: Add `Documentation` property to `NamedSchema`
* AVRO-2155: Add documentation to generated code
---
lang/csharp/src/apache/main/CodeGen/CodeGen.cs | 15 +++++++++
lang/csharp/src/apache/main/Schema/EnumSchema.cs | 10 ++++--
lang/csharp/src/apache/main/Schema/FixedSchema.cs | 10 ++++--
lang/csharp/src/apache/main/Schema/NamedSchema.cs | 12 ++++++-
lang/csharp/src/apache/main/Schema/RecordSchema.cs | 10 ++++--
lang/csharp/src/apache/test/Schema/SchemaTests.cs | 39 ++++++++++++++++++++++
6 files changed, 86 insertions(+), 10 deletions(-)
diff --git a/lang/csharp/src/apache/main/CodeGen/CodeGen.cs
b/lang/csharp/src/apache/main/CodeGen/CodeGen.cs
index 7e70a02..2bcebab 100644
--- a/lang/csharp/src/apache/main/CodeGen/CodeGen.cs
+++ b/lang/csharp/src/apache/main/CodeGen/CodeGen.cs
@@ -260,6 +260,11 @@ namespace Avro
ctd.Attributes = MemberAttributes.Public;
ctd.BaseTypes.Add("SpecificFixed");
+ if (fixedSchema.Documentation != null)
+ {
+ ctd.Comments.Add(createDocComment(fixedSchema.Documentation));
+ }
+
// create static schema field
createSchemaField(schema, ctd, true);
@@ -306,6 +311,11 @@ namespace Avro
ctd.IsEnum = true;
ctd.Attributes = MemberAttributes.Public;
+ if (enumschema.Documentation != null)
+ {
+ ctd.Comments.Add(createDocComment(enumschema.Documentation));
+ }
+
foreach (string symbol in enumschema.Symbols)
{
if (CodeGenUtil.Instance.ReservedKeywords.Contains(symbol))
@@ -526,6 +536,11 @@ namespace Avro
ctd.IsClass = true;
ctd.IsPartial = true;
+ if (recordSchema.Documentation != null)
+ {
+ ctd.Comments.Add(createDocComment(recordSchema.Documentation));
+ }
+
createSchemaField(schema, ctd, isError);
// declare Get() to be used by the Writer classes
diff --git a/lang/csharp/src/apache/main/Schema/EnumSchema.cs
b/lang/csharp/src/apache/main/Schema/EnumSchema.cs
index fc21d14..93c36c7 100644
--- a/lang/csharp/src/apache/main/Schema/EnumSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/EnumSchema.cs
@@ -70,7 +70,8 @@ namespace Avro
symbolMap[s] = i++;
symbols.Add(s);
}
- return new EnumSchema(name, aliases, symbols, symbolMap, props,
names);
+ return new EnumSchema(name, aliases, symbols, symbolMap, props,
names,
+ JsonHelper.GetOptionalString(jtok, "doc"));
}
/// <summary>
@@ -80,10 +81,13 @@ namespace Avro
/// <param name="aliases">list of aliases for the name</param>
/// <param name="symbols">list of enum symbols</param>
/// <param name="symbolMap">map of enum symbols and value</param>
+ /// <param name="props">custom properties on this schema</param>
/// <param name="names">list of named schema already read</param>
+ /// <param name="doc">documentation for this named schema</param>
private EnumSchema(SchemaName name, IList<SchemaName> aliases,
List<string> symbols,
- IDictionary<String, int> symbolMap, PropertyMap
props, SchemaNames names)
- : base(Type.Enumeration, name, aliases, props,
names)
+ IDictionary<String, int> symbolMap, PropertyMap
props, SchemaNames names,
+ string doc)
+ : base(Type.Enumeration, name, aliases, props,
names, doc)
{
if (null == name.Name) throw new SchemaParseException("name cannot
be null for enum schema.");
this.Symbols = symbols;
diff --git a/lang/csharp/src/apache/main/Schema/FixedSchema.cs
b/lang/csharp/src/apache/main/Schema/FixedSchema.cs
index 67c843d..8739921 100644
--- a/lang/csharp/src/apache/main/Schema/FixedSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/FixedSchema.cs
@@ -44,7 +44,8 @@ namespace Avro
SchemaName name = NamedSchema.GetName(jtok, encspace);
var aliases = NamedSchema.GetAliases(jtok, name.Space,
name.EncSpace);
- return new FixedSchema(name, aliases,
JsonHelper.GetRequiredInteger(jtok, "size"), props, names);
+ return new FixedSchema(name, aliases,
JsonHelper.GetRequiredInteger(jtok, "size"), props, names,
+ JsonHelper.GetOptionalString(jtok, "doc"));
}
/// <summary>
@@ -53,9 +54,12 @@ namespace Avro
/// <param name="name">name of the fixed schema</param>
/// <param name="aliases">list of aliases for the name</param>
/// <param name="size">fixed size</param>
+ /// <param name="props">custom properties on this schema</param>
/// <param name="names">list of named schema already parsed in</param>
- private FixedSchema(SchemaName name, IList<SchemaName> aliases, int
size, PropertyMap props, SchemaNames names)
- : base(Type.Fixed, name, aliases, props, names)
+ /// <param name="doc">documentation for this named schema</param>
+ private FixedSchema(SchemaName name, IList<SchemaName> aliases, int
size, PropertyMap props, SchemaNames names,
+ string doc)
+ : base(Type.Fixed, name, aliases, props, names,
doc)
{
if (null == name.Name) throw new SchemaParseException("name cannot
be null for fixed schema.");
if (size <= 0) throw new ArgumentOutOfRangeException("size", "size
must be greater than zero.");
diff --git a/lang/csharp/src/apache/main/Schema/NamedSchema.cs
b/lang/csharp/src/apache/main/Schema/NamedSchema.cs
index 6963238..35966eb 100644
--- a/lang/csharp/src/apache/main/Schema/NamedSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/NamedSchema.cs
@@ -58,6 +58,11 @@ namespace Avro
}
/// <summary>
+ /// Documentation for the schema, if any. Null if there is no
documentation.
+ /// </summary>
+ public string Documentation { get; private set; }
+
+ /// <summary>
/// List of aliases for this named schema
/// </summary>
private readonly IList<SchemaName> aliases;
@@ -95,11 +100,16 @@ namespace Avro
/// </summary>
/// <param name="type">schema type</param>
/// <param name="name">name</param>
+ /// <param name="aliases">aliases for this named schema</param>
+ /// <param name="props">custom properties on this schema</param>
/// <param name="names">list of named schemas already read</param>
- protected NamedSchema(Type type, SchemaName name, IList<SchemaName>
aliases, PropertyMap props, SchemaNames names)
+ /// <param name="doc">documentation for this named schema</param>
+ protected NamedSchema(Type type, SchemaName name, IList<SchemaName>
aliases, PropertyMap props, SchemaNames names,
+ string doc)
: base(type, props)
{
this.SchemaName = name;
+ this.Documentation = doc;
this.aliases = aliases;
if (null != name.Name) // Added this check for anonymous records
inside Message
if (!names.Add(name, this))
diff --git a/lang/csharp/src/apache/main/Schema/RecordSchema.cs
b/lang/csharp/src/apache/main/Schema/RecordSchema.cs
index 8c32b69..b1495df 100644
--- a/lang/csharp/src/apache/main/Schema/RecordSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/RecordSchema.cs
@@ -75,7 +75,8 @@ namespace Avro
var fields = new List<Field>();
var fieldMap = new Dictionary<string, Field>();
var fieldAliasMap = new Dictionary<string, Field>();
- var result = new RecordSchema(type, name, aliases, props, fields,
request, fieldMap, fieldAliasMap, names);
+ var result = new RecordSchema(type, name, aliases, props, fields,
request, fieldMap, fieldAliasMap, names,
+ JsonHelper.GetOptionalString(jtok, "doc"));
int fieldPos = 0;
foreach (JObject jfield in jfields)
@@ -99,14 +100,17 @@ namespace Avro
/// <param name="type">type of record schema, either record or
error</param>
/// <param name="name">name of the record schema</param>
/// <param name="aliases">list of aliases for the record name</param>
+ /// <param name="props">custom properties on this schema</param>
/// <param name="fields">list of fields for the record</param>
/// <param name="request">true if this is an anonymous record with
'request' instead of 'fields'</param>
/// <param name="fieldMap">map of field names and field objects</param>
+ /// <param name="fieldAliasMap">map of field aliases and field
objects</param>
/// <param name="names">list of named schema already read</param>
+ /// <param name="doc">documentation for this named schema</param>
private RecordSchema(Type type, SchemaName name, IList<SchemaName>
aliases, PropertyMap props,
List<Field> fields, bool request,
IDictionary<string, Field> fieldMap,
- IDictionary<string, Field> fieldAliasMap,
SchemaNames names)
- : base(type, name, aliases, props, names)
+ IDictionary<string, Field> fieldAliasMap,
SchemaNames names, string doc)
+ : base(type, name, aliases, props, names, doc)
{
if (!request && null == name.Name) throw new
SchemaParseException("name cannot be null for record schema.");
this.Fields = fields;
diff --git a/lang/csharp/src/apache/test/Schema/SchemaTests.cs
b/lang/csharp/src/apache/test/Schema/SchemaTests.cs
index a1c3f3c..8e13087 100644
--- a/lang/csharp/src/apache/test/Schema/SchemaTests.cs
+++ b/lang/csharp/src/apache/test/Schema/SchemaTests.cs
@@ -196,6 +196,25 @@ namespace Avro.Test
testToString(sc);
}
+ [TestCase("{\"type\":\"record\",\"name\":\"LongList\"," +
+ "\"fields\":[{\"name\":\"f1\",\"type\":\"long\"}," +
+ "{\"name\":\"f2\",\"type\": \"int\"}]}",
+ null)]
+ [TestCase("{\"type\":\"record\",\"name\":\"LongList\"," +
+ "\"fields\":[{\"name\":\"f1\",\"type\":\"long\", \"default\":
\"100\"}," +
+ "{\"name\":\"f2\",\"type\": \"int\"}], \"doc\": \"\"}",
+ "")]
+ [TestCase("{\"type\":\"record\",\"name\":\"LongList\"," +
+ "\"fields\":[{\"name\":\"f1\",\"type\":\"long\", \"default\":
\"100\"}," +
+ "{\"name\":\"f2\",\"type\": \"int\"}], \"doc\": \"this is a
test\"}",
+ "this is a test")]
+ public void TestRecordDoc(string s, string expectedDoc)
+ {
+ var rs = Schema.Parse(s) as RecordSchema;
+ Assert.IsNotNull(rs);
+ Assert.AreEqual(expectedDoc, rs.Documentation);
+ }
+
[TestCase("{\"type\": \"enum\", \"name\": \"Test\", \"symbols\":
[\"A\", \"B\"]}",
new string[] { "A", "B" })]
public void TestEnum(string s, string[] symbols)
@@ -215,6 +234,16 @@ namespace Avro.Test
testToString(sc);
}
+ [TestCase("{\"type\": \"enum\", \"name\": \"Test\", \"symbols\":
[\"A\", \"B\"]}", null)]
+ [TestCase("{\"type\": \"enum\", \"name\": \"Test\", \"symbols\":
[\"A\", \"B\"], \"doc\": \"\"}", "")]
+ [TestCase("{\"type\": \"enum\", \"name\": \"Test\", \"symbols\":
[\"A\", \"B\"], \"doc\": \"this is a test\"}", "this is a test")]
+ public void TestEnumDoc(string s, string expectedDoc)
+ {
+ var es = Schema.Parse(s) as EnumSchema;
+ Assert.IsNotNull(es);
+ Assert.AreEqual(expectedDoc, es.Documentation);
+ }
+
[TestCase("{\"type\": \"array\", \"items\": \"long\"}", "long")]
public void TestArray(string s, string item)
{
@@ -266,6 +295,16 @@ namespace Avro.Test
testToString(sc);
}
+ [TestCase("{ \"type\": \"fixed\", \"name\": \"Test\", \"size\": 1}",
null)]
+ [TestCase("{ \"type\": \"fixed\", \"name\": \"Test\", \"size\": 1,
\"doc\": \"\"}", "")]
+ [TestCase("{ \"type\": \"fixed\", \"name\": \"Test\", \"size\": 1,
\"doc\": \"this is a test\"}", "this is a test")]
+ public void TestFixedDoc(string s, string expectedDoc)
+ {
+ var fs = Schema.Parse(s) as FixedSchema;
+ Assert.IsNotNull(fs);
+ Assert.AreEqual(expectedDoc, fs.Documentation);
+ }
+
[TestCase("a", "o.a.h", Result = "o.a.h.a")]
public string testFullname(string s1, string s2)
{
