Use documentation comments to generate schema documentation

[alefcarlos]

Given this example:

using System;
using System.Runtime.Serialization;

namespace Super.GlobalPlatform.Authorizer.Events
{
    /// <summary>
    /// Summary record test
    /// </summary>
    [DataContract(Name = nameof(EventA), Namespace = "namespace.name")]
    public class EventA
    {
        /// <summary>
        /// Summary field Test
        /// </summary>
        [DataMember]
        public Guid TransactionId { get; set; }
    }
}

Generated avro output:

{
    "name": "namespace.name.EventA",
    "type": "record",
    "fields": [
        {
            "name": "TransactionId",
            "type": {
                "type": "string",
                "logicalType": "uuid"
            }
        }
    ]
}

• Is there any way to generate the field doc for record ?
• Why namespace field is ommited on the record ?

[dstelljes]

doc can’t be generated from <summary> since reflection doesn’t expose information contained in documentation comments. I don’t see any way to set documentation using the data contract attributes, but we could look at supporting other attributes; maybe something from System.ComponentModel would be a good fit.

Instead of including the namespace attribute, the schema writer prefers to fully qualify name. The rationale for that behavior is that it aligns with Parsing Canonical Form.

[alefcarlos]

Thank you so much! I really appreciate your quickly responses.

What about using documentation xml to get summary info ?

[dstelljes]

I think we’d be open to trying it... It should generally be safe to locate the file using Assembly.Location, and it looks like there are some classes in Microsoft.CodeAnalysis that could help parse.