While there doesn't seem to be an official syntax definition for links within a proto document, the syntax employed within the gRPC documentation is to utilize square brackets. Example:
// A developer-facing error message, which should be in English. Any
// user-facing error message should be localized and sent in the
// [google.rpc.Status.details][google.rpc.Status.details] field, or localized by the client.
string message = 2;
// The name of the resource being accessed. For example, a shared calendar
// name: "example.com_4fghdhgsrgh@group.calendar.google.com", if the current
// error is [google.rpc.Code.PERMISSION_DENIED][google.rpc.Code.PERMISSION_DENIED].
string resource_name = 2;
It would be nice if these links were properly rendered within the output. For links to external documents/packages, I think they should also be supported provided that the referenced package is included in the protoc --doc_out=x ... file list.
For a link to a package/document not in the argument list, I'm not sure. Perhaps we render as superscript (throwing a warning during generation). If protoc-gen-doc had the option for generating multiple output documents (one per file/package), and there were an established naming convention for the package name to the output file name, we could generate a link to the document as it would be named if it existed. And let the user assume responsibility for making sure that document exists.
While there doesn't seem to be an official syntax definition for links within a proto document, the syntax employed within the gRPC documentation is to utilize square brackets. Example:
https://github.com/grpc/grpc/blob/2357b2de2c031a93c2af585bcc07de1c37102365/src/proto/grpc/status/status.proto#L86
The first part is the display text and the second part is the link target and is the same for linking outside the current document: https://github.com/googleapis/googleapis/blob/d051457d08e6b24864e171207785e6f02bfbfa7f/google/rpc/error_details.proto#L157
It would be nice if these links were properly rendered within the output. For links to external documents/packages, I think they should also be supported provided that the referenced package is included in the
protoc --doc_out=x ...file list. For a link to a package/document not in the argument list, I'm not sure. Perhaps we render as superscript (throwing a warning during generation). If protoc-gen-doc had the option for generating multiple output documents (one per file/package), and there were an established naming convention for the package name to the output file name, we could generate a link to the document as it would be named if it existed. And let the user assume responsibility for making sure that document exists.