[
https://issues.apache.org/jira/browse/AVRO-3854?page=com.atlassian.jira.plugin.system.issuetabpanels:comment-tabpanel&focusedCommentId=17764059#comment-17764059
]
Kalle Niemitalo commented on AVRO-3854:
---------------------------------------
Demo schema:
{code:JSON}
{
"type": "record",
"name": "demo.Demo",
"fields": [
{
"name": "srid",
"type": "int",
"doc": "Spatial reference system identifier
<https://en.wikipedia.org/w/index.php?title=Spatial_reference_system&oldid=1172406524#Identifiers>"
}
]
}
{code}
Generate C# code with with {{dotnet tool run avrogen -s demo.avsc .}}
The generated "demo/Demo.cs" file has XML documentation comments like this:
{code:C#}
/// <summary>
/// Spatial reference system identifier
<https://en.wikipedia.org/w/index.php?title=Spatial_reference_system&oldid=1172406524#Identifiers>
/// </summary>
private int _srid;
public virtual global::Avro.Schema Schema
{
get
{
return Demo._SCHEMA;
}
}
/// <summary>
/// Spatial reference system identifier
<https://en.wikipedia.org/w/index.php?title=Spatial_reference_system&oldid=1172406524#Identifiers>
/// </summary>
public int srid
{
get
{
return this._srid;
}
set
{
this._srid = value;
}
}
{code}
Building that causes these warnings that should be avoided:
{code:none}
demo\Demo.cs(23,50): warning CS1570: XML comment has badly formed XML -- 'An
identifier was expected.'
demo\Demo.cs(23,50): warning CS1570: XML comment has badly formed XML -- 'The
character(s) '/' cannot be used at this location.'
demo\Demo.cs(24,9): warning CS1570: XML comment has badly formed XML -- 'End
tag 'summary' does not match the start tag 'https:'.'
demo\Demo.cs(25,1): warning CS1570: XML comment has badly formed XML --
'Expected an end tag for element 'summary'.'
demo\Demo.cs(34,50): warning CS1570: XML comment has badly formed XML -- 'An
identifier was expected.'
demo\Demo.cs(34,50): warning CS1570: XML comment has badly formed XML -- 'The
character(s) '/' cannot be used at this location.'
demo\Demo.cs(35,9): warning CS1570: XML comment has badly formed XML -- 'End
tag 'summary' does not match the start tag 'https:'.'
demo\Demo.cs(36,1): warning CS1570: XML comment has badly formed XML --
'Expected an end tag for element 'summary'.'
{code}
The compiler-generated XML documentation file does not have any documentation
in it:
{code:XML}
<?xml version="1.0"?>
<doc>
<assembly>
<name>Demo</name>
</assembly>
<members>
<!-- Badly formed XML comment ignored for member "F:demo.Demo._srid" -->
<!-- Badly formed XML comment ignored for member "P:demo.Demo.srid" -->
</members>
</doc>
{code}
> C# avrogen copies "doc" property to XML doc comment even if it is not valid
> XML
> -------------------------------------------------------------------------------
>
> Key: AVRO-3854
> URL: https://issues.apache.org/jira/browse/AVRO-3854
> Project: Apache Avro
> Issue Type: Bug
> Components: csharp, tools
> Affects Versions: 1.11.1
> Reporter: Kalle Niemitalo
> Priority: Minor
>
> The C# "avrogen" tool copies the values of "doc" properties from the schema
> to XML documentation comments in the generated C# files. If the "doc"
> property contains XML reserved characters but is not valid XML, then they
> will cause warnings when the generated C# file is later compiled. This can
> happen if the "doc" property is e.g. Markdown intended to be processed by a
> different tool.
> The "avrogen" tool should either encode the XML reserved characters or
> provide a way to omit the XML documentation comments entirely.
--
This message was sent by Atlassian Jira
(v8.20.10#820010)
