Add documentation to proto files

protos/hardware/hardware.proto

@@ -6,36 +6,58 @@ package github.com.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 .