You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@avro.apache.org by "ASF GitHub Bot (JIRA)" <ji...@apache.org> on 2018/12/05 14:53:00 UTC
[jira] [Commented] (AVRO-2155) Generate documentation for C#
classes and enums
[ https://issues.apache.org/jira/browse/AVRO-2155?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=16710146#comment-16710146 ]
ASF GitHub Bot commented on AVRO-2155:
--------------------------------------
dkulp closed pull request #296: AVRO-2155: Include documentation for named schemas in generated code
URL: https://github.com/apache/avro/pull/296
This is a PR merged from a forked repository.
As GitHub hides the original diff on merge, it is displayed below for
the sake of provenance:
As this is a foreign pull request (from a fork), the diff is supplied
below (as it won't show otherwise due to GitHub magic):
diff --git a/lang/csharp/src/apache/main/CodeGen/CodeGen.cs b/lang/csharp/src/apache/main/CodeGen/CodeGen.cs
index 7e70a02d5..2bcebabd9 100644
--- a/lang/csharp/src/apache/main/CodeGen/CodeGen.cs
+++ b/lang/csharp/src/apache/main/CodeGen/CodeGen.cs
@@ -260,6 +260,11 @@ protected virtual void processFixed(Schema schema)
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 @@ protected virtual void processEnum(Schema schema)
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 @@ protected virtual CodeTypeDeclaration processRecord(Schema schema)
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 fc21d14b7..93c36c7ef 100644
--- a/lang/csharp/src/apache/main/Schema/EnumSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/EnumSchema.cs
@@ -70,7 +70,8 @@ internal static EnumSchema NewInstance(JToken jtok, PropertyMap props, SchemaNam
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 @@ internal static EnumSchema NewInstance(JToken jtok, PropertyMap props, SchemaNam
/// <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 67c843d9a..873992116 100644
--- a/lang/csharp/src/apache/main/Schema/FixedSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/FixedSchema.cs
@@ -44,7 +44,8 @@ internal static FixedSchema NewInstance(JToken jtok, PropertyMap props, SchemaNa
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 @@ internal static FixedSchema NewInstance(JToken jtok, PropertyMap props, SchemaNa
/// <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 e0bfab0aa..62fb14566 100644
--- a/lang/csharp/src/apache/main/Schema/NamedSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/NamedSchema.cs
@@ -57,6 +57,11 @@ public string Fullname
get { return SchemaName.Fullname; }
}
+ /// <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>
@@ -95,11 +100,16 @@ internal static NamedSchema NewInstance(JObject jo, PropertyMap props, SchemaNam
/// </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 8c32b6913..b1495dff0 100644
--- a/lang/csharp/src/apache/main/Schema/RecordSchema.cs
+++ b/lang/csharp/src/apache/main/Schema/RecordSchema.cs
@@ -75,7 +75,8 @@ internal static RecordSchema NewInstance(Type type, JToken jtok, PropertyMap pro
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 @@ internal static RecordSchema NewInstance(Type type, JToken jtok, PropertyMap pro
/// <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 7931d405b..e49abfd8e 100644
--- a/lang/csharp/src/apache/test/Schema/SchemaTests.cs
+++ b/lang/csharp/src/apache/test/Schema/SchemaTests.cs
@@ -195,6 +195,25 @@ public void TestRecord(string s, string[] kv)
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)
@@ -214,6 +233,16 @@ public void TestEnum(string s, string[] symbols)
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)
{
@@ -265,6 +294,16 @@ public void TestFixed(string s, int size)
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)
{
----------------------------------------------------------------
This is an automated message from the Apache Git Service.
To respond to the message, please log on GitHub and use the
URL above to go to the specific comment.
For queries about this service, please contact Infrastructure at:
users@infra.apache.org
> Generate documentation for C# classes and enums
> -----------------------------------------------
>
> Key: AVRO-2155
> URL: https://issues.apache.org/jira/browse/AVRO-2155
> Project: Apache Avro
> Issue Type: New Feature
> Components: csharp
> Affects Versions: 1.8.2
> Reporter: Brian Lachniet
> Priority: Minor
>
> Update the C# "avrogen" code generation to populate documentation for code entities (classes and enums) that are generated from named schemas (record, enum and fixed). At this time, it only generates documentation for Avro fields (C# fields and properties).
--
This message was sent by Atlassian JIRA
(v7.6.3#76005)