Add documentation to proto files (#243)

## 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?

<!--- Please describe in detail how you tested your changes. -->
<!--- Include details of your testing environment, and the tests you ran to -->
<!--- see how your change affects other areas of the code, etc. -->


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

<!--- Fixes a bug, unblocks installation, removes a component of the stack etc -->
<!--- Requires a DB migration script, etc. -->


## Checklist:

I have:

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

protos/hardware/hardware.proto

@@ -6,36 +6,58 @@ package jackfan.us.kg.tinkerbell.tink.protos.hardware;
 
 import "google/api/annotations.proto";
 
+// The HardwareService provides access to data describing the compute
+// and networking profiles of the hardware available to accept workflows.
+//
+// The API supports adding new entries. While the hardware data is essential,
+// not all of the properties are required for every workflow. The choice of
+// workflow predicates the level of hardware detail necessary.
+//
+// Read access to individual hardware profiles is provided through the unique
+// ID, MAC, and IP hardware properties.
 service HardwareService {
+	// Push adds a new Hardware profile to the data store.
 	rpc Push (PushRequest) returns (Empty) {
 		option (google.api.http) = {
             post: "/v1/hardware"
             body: "*"
         };
 	};
+
+	// ByMac returns the Hardware with the given hardware MAC Address.
 	rpc ByMAC(GetRequest) returns (Hardware) {
 		option (google.api.http) = {
             post: "/v1/hardware/mac"
             body: "*"
         };
 	};
+
+	// ByIP returns the Hardware with the given IP Address.
 	rpc ByIP(GetRequest) returns (Hardware) {
 		option (google.api.http) = {
             post: "/v1/hardware/ip"
             body: "*"
         };
 	};
+
+	// ByID returns the Hardware with the given ID.
 	rpc ByID(GetRequest) returns (Hardware) {
 		option (google.api.http) = {
             get: "/v1/hardware/{id}"
         };
 	};
+
+	// All returns all of the Hardware profiles.
 	rpc All(Empty) returns (stream Hardware) {
 		option (google.api.http) = {
             get: "/v1/hardware"
         };
 	};
+
+	// Watch watches for events on the given hardware and streams the matching Hardware.
 	rpc Watch(GetRequest) returns (stream Hardware);
+
+	// Delete deletes the given hardware from the data store.
 	rpc Delete(DeleteRequest) returns (Empty) {
     option (google.api.http) = {
             delete: "/v1/hardware/{id}"

protos/protoc.sh

@@ -1,9 +1,33 @@
 #!/usr/bin/env bash
-
+#
+# protoc.sh uses the local protoc if installed, otherwise
+# docker will be used with a complete environment provided
+# by https://github.com/jaegertracing/docker-protobuf.
+# Alternative images like grpc/go are very dated and do not
+# include the needed plugins and includes.
+#
 set -e
 
+GOPATH=${GOPATH:-$(go env GOPATH)}
+
+if command -v protoc >/dev/null; then
+	GW_PATH="$GOPATH"/src/github.com/grpc-ecosystem/grpc-gateway
+	GO111MODULES=on go get github.com/grpc-ecosystem/grpc-gateway/protoc-gen-grpc-gateway
+
+	PROTOC="protoc -I/usr/local/include -I$GW_PATH/third_party/googleapis --plugin=protoc-gen-grpc-gateway=$GOPATH/bin/protoc-gen-grpc-gateway"
+else
+	IMAGE=jaegertracing/protobuf:0.2.0
+	BASE=/protos
+	PROTOC="docker run -v $(pwd):$BASE -w $BASE --rm $IMAGE "
+fi
+
 for proto in hardware packet template workflow; do
 	echo "Generating ${proto}.pb.go..."
-	protoc -I ./ -I ./common/ -I "$GOPATH"/src/github.com/grpc-ecosystem/grpc-gateway/third_party/googleapis "${proto}/${proto}.proto" --go_out=plugins=grpc:./ --grpc-gateway_out=logtostderr=true:.
+	$PROTOC -I./ \
+		-I./common \
+		--go_opt=paths=source_relative \
+		--go_out=plugins=grpc:./ \
+		--grpc-gateway_out=logtostderr=true:. \
+		"${proto}/${proto}.proto"
 done
 goimports -w .