api-linter

api-linter copied to clipboard

The page at https://linter.aip.dev/203/optional should have the following for the sample code:

// Correct. import "google/api/field_behavior.proto";

message Book { string name = 1;

// The foreword for the book. string foreword = 2 [(google.api.field_behavior) = OPTIONAL]; }

Hmm. I take the point, but in general we have not done imports across most of these.

I assume this was an issue for you, or else you would not have filed the bug. I am hesitant to go make "universal import statements" a policy, though. Is there an "in-between" approach that would be less confusing for you?

I was directed to that page as a guideline on how to fix a linter error.

It's always handy, when this happens, for the page to tell you everything you need to know to fix the error. So as well as the syntax example (which is there, and easily copyable), it would be nice to know what you need to include in order to fix the issue. I'm not wedded to any one approach, but knowing that import "google/api/field_behavior.proto"; was the text I need to ad to the file would have been useful.

Thanks,

Alasdair

Perhaps instead we can auto-link the annotation types to their corresponding definition in https://github.com/googleapis/googleapis? Most of the examples in the docs are not syntactically complete proto files.

We also now have a new site generator for aip.dev that knows how to include snippets of an actual file. We could shift toward that (and that could be useful for testing reasons also).