Add more documentation about code generation #83
Conversation
Motivation: Users (especially new ones) often have issues with generating code. This package provide a number of ways to do this but doesn't do a good job of explaining the pros and cons of each method or how to use each of them. Modifications: - Split up the generating stubs doc into four parts: one article for each method explaining how to use that approach. For the build plugin and protoc the content was more or less directly moves from the existing doc. - Reprurpose the existing generating stubs doc to explain the pros and cons of each approach to make it easier for users to decide. Result: Better docs
| protoc --plugin=/path/to/protoc-gen-grpc-swift-2 --grpc-swift-2_out=. my-service.proto | ||
| ``` | ||
|
|
||
| You can also specify various option the `protoc-gen-grpc-swift-2` via `protoc` using |
There was a problem hiding this comment.
| You can also specify various option the `protoc-gen-grpc-swift-2` via `protoc` using | |
| You can specify an option to the `protoc-gen-grpc-swift-2` plugin via `protoc` using |
There was a problem hiding this comment.
I think neither of these are right 😀
| > `protoc-gen-grpc-swift-2` only generates gRPC stubs, it doesn't generate messages. You must use | ||
| > `protoc-gen-swift` to generate messages in addition to gRPC Stubs. |
There was a problem hiding this comment.
I'm unsure about this, but should we maybe put this at the top of this section and slightly rephrase it to something like "you should first make sure you've generated your proto messages by using protoc-gen-swift before generating gRPC Stubs?
I just feel like if you're completely new to all of this, this paragraph may be confusing?
There was a problem hiding this comment.
It doesn't matter which order they're generated in, it can be before or after generating gRPC stubs. I think this is in the right place because the paragraph above sets the scene by explaining that we provide a plugin for protoc which generates the gRPC bits. This is just making it more explicit that it only generates the gRPC bits.
| protoc --grpc-swift-2_opt=<OPTION_NAME>=<OPTION_VALUE> --grpc-swift-2_out=. | ||
| ``` | ||
|
|
||
| You can specify multiple options by passing the `--grpc-swift-2_opt` argument multiple times: |
There was a problem hiding this comment.
| You can specify multiple options by passing the `--grpc-swift-2_opt` argument multiple times: | |
| You can also specify multiple options by passing the `--grpc-swift-2_opt` argument multiple times: |
Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-the-build-plugin.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Gus Cairo <[email protected]>
| > `protoc-gen-grpc-swift-2` only generates gRPC stubs, it doesn't generate messages. You must use | ||
| > `protoc-gen-swift` to generate messages in addition to gRPC Stubs. |
There was a problem hiding this comment.
It doesn't matter which order they're generated in, it can be before or after generating gRPC stubs. I think this is in the right place because the paragraph above sets the scene by explaining that we provide a plugin for protoc which generates the gRPC bits. This is just making it more explicit that it only generates the gRPC bits.
| protoc --plugin=/path/to/protoc-gen-grpc-swift-2 --grpc-swift-2_out=. my-service.proto | ||
| ``` | ||
|
|
||
| You can also specify various option the `protoc-gen-grpc-swift-2` via `protoc` using |
There was a problem hiding this comment.
I think neither of these are right 😀
Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-protoc.md
Outdated
Show resolved
Hide resolved
Sources/GRPCProtobuf/Documentation.docc/Articles/Code-generation-with-protoc.md
Outdated
Show resolved
Hide resolved
Motivation:
Users (especially new ones) often have issues with generating code. This package provide a number of ways to do this but doesn't do a good job of explaining the pros and cons of each method or how to use each of them.
Modifications:
Result:
Better docs