Add documentation to proto files

[displague]

Description

This PR:

• makes protos/protoc.sh executable in environments without protoc (and c++) installed
• docker provides a reproducible protoc environment for regenerating pb.go files (jaegertracing/protobuf, libprotoc 3.8.0)
• adds documentation to the hardware.proto file

Why is this needed

This starts the effort needed for #219

Additional .proto file docs would be needed to close that issue.

How Has This Been Tested?

Let me know how I should test this.

I would like to include a make protos task.
Should this be run by CI to check for uncommitted drift?

How are existing users impacted? What migration steps/scripts do we need?

Checklist:

I have:

• updated the documentation and/or roadmap (if required)
• added unit or e2e tests
• provided instructions on how to upgrade

[gianarb]

I like the end goal: documentation and easy to replicate. But this adds a dependency with Docker and I don't like that in the same way.

If this is something you would like to add-in CI we use nix and shell.nix to resolve dependencies in the ci-checks.sh can you follow the same pattern?

[displague]

this adds a dependency with Docker and I don't like that in the same way.

What are your thoughts on taking this PR as-is for the documentation changes and the protoc.sh changes (when the existing tests pass)?

If protoc is already installed, it won't use Docker. The protoc.sh script generates the .pb.go files that should be included in each commit (that modifies .proto files), it needs to be run by the developer locally.

The protoc.sh script is not usable without protoc installed, which is complicated because you need to use a package manager, download and unzip, or compile it (requiring a c++ environment). This makes me ❤️ go get even more.

I haven't added any build time changes in this PR. We could make this a part of CI later.

Independent of that, we can create a make protos task, which could replace the protoc.sh script.

Then, as I see it, make protos will have to do one of four things:

1. Require the expected version of protoc to be installed, with an additional requirement for the expected version of the proto includes from Google
2. or install these tools for you (in a version and build path isolated way)
3. or use an existing Docker image
4. or use and maintain our own Docker image

1 and 3 are the most sustainable, 3 is the easiest on new contributors.

[codecov]

Codecov Report

Merging #243 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master     #243   +/-   ##
=======================================
  Coverage   22.90%   22.90%           
=======================================
  Files          15       15           
  Lines        1275     1275           
=======================================
  Hits          292      292           
  Misses        964      964           
  Partials       19       19           

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 7dec4d8...4146325. Read the comment docs.

[kqdeng]

Small nitpick, can you run goimports so that the imports inside the pb.go files get grouped properly?

[mmlb]

#283 is relevant to this, 6f757ec addresses @kdeng3849's feedback too.

[displague]

@kdeng3849 @mmlb thanks for the goimports addition!

This is rebased and ready for another look.