Include source info?

[shadiramadan]

How do I include source info (comments) when using protoc-gen-es ?

For go @jhump made a nice helper to add them back:

• github.com/jhump/protoreflect/v2/sourceinfo/cmd/protoc-gen-gosrcinfo

It would be nice if this was just a simple protoc setting we could set to prevent them being stripped out!

I'm trying to avoid needing to write a helper to add them back myself!

[timostamm]

Hey Shadi, there is no option to include source info in embedded descriptors for similar reasons it isn't an option in protoc-gen-go: It would significantly increase the size of generated code.

Of course there are good reasons to include them in certain situations, but we're very conservative adding new options to the plugin because supporting them isn't free.

That said, there are alternatives to still get the source code info. Let's say we want to retrieve the comment on this message:

syntax = "proto3";
package example;

// Hello message
message User {
  string first_name = 1;
  string last_name = 2;
}

This script won't print any comments, because source code info isn't included in generated code:

import {UserSchema} from "./gen/example_pb";
import {getComments} from "@bufbuild/protoplugin";

const messageComments = getComments(UserSchema);
console.log(messageComments); // no comments

But this script will:

import {readFileSync} from "node:fs";
import {fromBinary} from "@bufbuild/protobuf";
import {FileDescriptorSetSchema} from "@bufbuild/protobuf/wkt";
import {createCommentGetter} from "./comment-getter.js";
import {UserSchema} from "./gen/example_pb.js";

// create descriptors.binpb with `buf build -o descriptors.binpb` or `protoc -o descriptors.binpb --include_source_info`
const fileDescriptorSet = fromBinary(FileDescriptorSetSchema, readFileSync("descriptors.binpb"));
const getComments = createCommentGetter(fileDescriptorSet);

const messageComments = getComments(UserSchema);
console.log(messageComments); // comments!

comment-getter.ts

import {type AnyDesc, createFileRegistry, type DescComments, type DescFile} from "@bufbuild/protobuf";
import {getComments} from "@bufbuild/protoplugin";
import type {FileDescriptorSet} from "@bufbuild/protobuf/wkt";

export function createCommentGetter(fileDescriptorSet: FileDescriptorSet) {
  const registry = createFileRegistry(fileDescriptorSet);
  return function commentGetter(desc: Exclude<AnyDesc, DescFile>): DescComments {
    let descWithComments: Exclude<AnyDesc, DescFile> | undefined;
    switch (desc.kind) {
      case "extension":
      case "enum":
      case "message":
      case "service":
        descWithComments = registry.get(desc.typeName);
        break;
      case "field": {
        const descParentWithComments = registry.getMessage(desc.parent.typeName);
        descWithComments = descParentWithComments.fields.find(d => d.name === desc.name);
        break;
      }
      case "rpc": {
        const descParentWithComments = registry.getService(desc.parent.typeName);
        descWithComments = descParentWithComments.methods.find(d => d.name === desc.name);
        break;
      }
      case "oneof": {
        const descParentWithComments = registry.getMessage(desc.parent.typeName);
        descWithComments = descParentWithComments.oneofs.find(d => d.name === desc.name);
        break;
      }
      case "enum_value": {
        const descParentWithComments = registry.getEnum(desc.parent.typeName);
        descWithComments = descParentWithComments.values.find(d => d.name === desc.name);
        break;
      }
    }
    return getComments(descWithComments ?? desc);
  }
}

Your use case may vary, but the idea is to build a file descriptor set that does include source code info at the same build step where you generate code, and retrieve comments from there.

Thanks for filing the issue. Hopefully we can provide better support for source code info in the future.