pseudomuto / protoc-gen-doc

Documentation generator plugin for Google Protocol Buffers
MIT License
2.61k stars 462 forks source link

Custom EnumValueOptions in protobuf added to markdown #416

Closed chrisstockton closed 4 years ago

chrisstockton commented 4 years ago

Is there a way to get EnumValueOptions in the doc output?

For example, if I make a slight modification to vehicle.proto by adding an EnumValueOptions to the Category enum:

syntax = "proto3";

import "google/protobuf/descriptor.proto";

package com.example;

# Add some annotations to the Category enum
extend google.protobuf.EnumValueOptions {
    repeated string fields = 50001; /** required fields */
}

enum Category {
  CATEGORY_INHOUSE  = 0 [(fields) = "some_value"];  /** The manufacturer is inhouse. */
  CATEGORY_EXTERNAL = 1 [(fields) = "another_value"]; /** The manufacturer is external. */
}

message Manufacturer {
  /**
   * Manufacturer category. A manufacturer may be either inhouse or external.
   */

  int32 id       = 1; /** The unique manufacturer ID. */
  string code    = 2; /** A manufacturer code, e.g. "DKL4P". */
  string details = 3; /** Manufacturer details (minimum orders et.c.). */

  /** Manufacturer category. */
  Category category = 4;
}

I would like to get the annotations, [(fields) = "some_value"], added to the generated table:

Category

NameOfEnum Number Description Fields
CATEGORY_INHOUSE 0 The manufacturer is inhouse. some_value
CATEGORY_EXTERNAL 1 The manufacturer is external. another_value

I see there's some support for some similar types of things, like defaults, [default = 50] and some validation related code, but couldn't figure out if that would for my case.

As far as I can tell, it looks like I'll need to create my own plugin using protokit to pull those values out of my protobuf definitions and render them with a custom template.

chrisstockton commented 4 years ago

Custom plugin and template it is.