Search code examples
c#.netprotocol-buffersprotobuf-netdocumentation-generation

Preserving proto comments when generating C# with protobuf-net


We are using protobuf-net to handle our Protocol Buffer needs in a C# application. Since we share our .proto files with other, non-managed applications, we are generating our code from the .proto files (not using the code-first protobuf-net approach). In order to stay as DRY as possible, we keep a lot of interface documentation inside the .proto files themselves. We generate the C# code by means of protogen.exe, called by a project build target.

Now, is there any way to (automatically) transfer these comments into the compiled C# code?

Basically, given a .proto like this:

// This message is used to request a resource from the server
message GetResource
{
    // The identifier of the requested resource 
    required string resourceId = 1;
}

...I would like something like this (IExtensible methods omitted for readability):

/// <summary>
/// This message is used to request a resource from the server
/// </summary>
[global::System.Serializable,global::ProtoBuf.ProtoContract(Name=@"GetResource")]
public partial class GetResource : global::ProtoBuf.IExtensible
{
    public GetResource() {}

    private string _resourceId;

    /// <summary>
    /// The identifier of the requested resource 
    /// [Required] <-- Would be nice...
    /// </summary>
    [global::ProtoBuf.ProtoMember(1, IsRequired = true, Name=@"resourceId", 
    DataFormat = global::ProtoBuf.DataFormat.Default)]
    public string ResourceId
    {
        get { return _resourceId; }
        set { _resourceId = value; }
    }
}

Solution

  • At the current time, I believe the answer is "no". To the best of my knowledge, "protoc" (Google's tool for parsing .proto files, which is used under the hood) silently discards the comments - so there is nothing available to read from. If a custom parser was written, then yes it would be possible, but there is also a language ambiguity about which comments apply to which lines, for example:

    // this probably relates to resourceId
    required string resourceId = 1;
    
    required int foo = 2; // but... is this foo? or bar?
                          // and what about this?
    
           // what does this relate to? and why?
    
    // and this? what are the rules?
    required int bar = 3;
    

    So for 2 different reasons: at the moment, no. All suggestions considered, though... especially if they come with a custom parser included :)

    Note that AFAIK this information is missing from most (all?) implementations for this reason. I'm happy to be corrected, though.