Skip to content

Commit cd9fe94

Browse files
Mr3zeeMr3zee
committed
GH comments
1 parent 1c84aed commit cd9fe94

File tree

1 file changed

+87
-85
lines changed

1 file changed

+87
-85
lines changed

‎docs/pages/kotlinx-rpc/topics/grpc-configuration.topic‎

Lines changed: 87 additions & 85 deletions
Original file line numberDiff line numberDiff line change
@@ -68,7 +68,7 @@
6868
</chapter>
6969
<chapter id="working-with-proto-files">
7070
<title>
71-
Working with <code>.proto</code> files
71+
Working with proto-files
7272
</title>
7373
<p>
7474
The minimum required configuration looks like this:
@@ -79,36 +79,24 @@
7979
}
8080
</code-block>
8181
<p>
82-
This will enable the code generation for your <code>.proto</code> files.
83-
We create special source sets for <code>.proto</code> files:
82+
This enables code generation for your <path>.proto</path> files.
83+
Special source sets are created for them:
8484
</p>
8585
<list>
8686
<li>
8787
<code>main</code> and <code>test</code> - source sets for Kotlin/JVM projects.
88-
Default source directories are <code>src/main/proto</code> and <code>src/test/proto</code>.
88+
Default source directories are <path>src/main/proto</path> and <path>src/test/proto</path>.
8989
</li>
9090
<li>
9191
<code>jvmMain</code> and <code>jvmTest</code> - source sets for Kotlin/Multiplatform projects.
92-
Default source directories are <code>src/jsmMain/proto</code> and <code>src/jvmTest/proto</code>.
92+
Default source directories are <path>src/jsmMain/proto</path> and <path>src/jvmTest/proto</path>.
9393
<warning>
94-
This will change to <code>src/commonMain/proto</code> and <code>src/commonTest/proto</code> in the
94+
These will change to <path>src/commonMain/proto</path> and <path>src/commonTest/proto</path> in the
9595
future.
9696
</warning>
97-
<note>
98-
Source set hierarchy is not supported, and we have no plans to support it.
99-
That means, for example,
100-
that you can't have <code>jsMain</code> and <code>jsTest</code> source sets for proto files.
101-
Same for native and WASM.
102-
Proto files can only be in the <code>jvmMain</code> and <code>jvmTest</code> source sets.
103-
(Later to be replaced with <code>commonMain</code> and <code>commonTest</code>)
104-
<br/>
105-
<br/>
106-
If you have a use case for other source sets and a hierarchy,
107-
please <a href="https://github.com/Kotlin/kotlinx-rpc/issues/new?template=feature_request.md">report it</a>.
108-
</note>
10997
</li>
11098
<li>
111-
Android source sets are not supported yet. <b>WIP</b>
99+
Android source set support is not available yet but will be included in a future release.
112100
</li>
113101
</list>
114102
<p>
@@ -133,30 +121,44 @@
133121
}
134122
</code-block>
135123
<p>
136-
By default, four source directories will be generated:
124+
By default, the following source directories are generated:
137125
</p>
138126
<list>
139127
<li>
140-
<code>java</code> - protobuf Java declarations, attached to <code>java</code> sources
128+
<code>java</code> - protobuf Java declarations, attached to <code>java</code> sources.
141129
</li>
142130
<li>
143-
<code>grpc-java</code> - gRPC Java declarations, attached to <code>java</code> sources
131+
<code>grpc-java</code> - gRPC Java declarations, attached to <code>java</code> sources.
144132
</li>
145133
<li>
146-
<code>grpc-kotlin</code> - gRPC Kotlin wrappers for Java, attached to <code>kotlin</code> sources
134+
<code>grpc-kotlin</code> - gRPC Kotlin wrappers for Java, attached to <code>kotlin</code> sources.
147135
</li>
148136
<li>
149-
<code>kotlinx-multiplatform</code> - our wrappers for all of the above, attached to <code>kotlin</code> sources
137+
<code>kotlin-multiplatform</code> - wrappers for all of the above, attached to <code>kotlin</code> sources.
150138
</li>
151139
</list>
152140
<note>
153-
Only the declarations from the <code>kotlinx-multiplatform</code> source set are intended to be used.
154-
The other ones are for internal use only and will be removed in the future.
141+
Only the declarations from the <code>kotlin-multiplatform</code> source set are intended to be used.
142+
The others are for internal use only and will be removed in a future release.
155143
</note>
156144
</chapter>
145+
<chapter title="Limitations" id="limitations">
146+
<p>
147+
Source set hierarchy is not supported, and we have no plans to support it.
148+
That means, for example,
149+
that you can't have <code>jsMain</code> and <code>jsTest</code> source sets for proto files.
150+
The same applies for native and Wasm targets.
151+
Currently, <path>.proto</path> files are only supported in the <code>jvmMain</code> and <code>jvmTest</code> source sets.
152+
(Later to be replaced with <code>commonMain</code> and <code>commonTest</code>)
153+
<br/>
154+
<br/>
155+
If you have a use case for other source sets and a hierarchy,
156+
please <a href="https://github.com/Kotlin/kotlinx-rpc/issues/new?template=feature_request.md">report it</a>.
157+
</p>
158+
</chapter>
157159
<chapter title="Protoc plugins" id="protoc-plugins">
158160
<p>
159-
To generate code, we need to use <a href="https://protobuf.dev/reference/other/">protoc plugins</a>.
161+
To generate code, we use <a href="https://protobuf.dev/reference/other/"><emphasis>protoc</emphasis> plugins</a>.
160162
By default, we use the following plugins:
161163
</p>
162164
<list>
@@ -172,7 +174,7 @@
172174
plugin.
173175
</li>
174176
<li>
175-
<code>kotlinx-multiplatform</code> - out own protoc plugin.
177+
<code>kotlin-multiplatform</code> - out own protoc plugin.
176178
</li>
177179
</list>
178180
<p>
@@ -195,17 +197,17 @@
195197
</code-block>
196198
<p>
197199
<code>protocPlugins</code> is a <code>NamedDomainObjectContainer&lt;ProtocPlugin&gt;</code>,
198-
which allows to add your own plugins.
200+
which allows you to add your own plugins.
199201
</p>
200202
<p>
201-
Every plugin is a <code>ProtocPlugin</code> class, that can be configured like this:
203+
Each plugin is represented by a <code>ProtocPlugin</code> and can be configured like this:
202204
</p>
203205
<code-block lang="Kotlin">
204-
// or like protocPlugins.kotlinMultiplatform for default plugins
206+
// Or use protocPlugins.kotlinMultiplatform for default plugins
205207
protocPlugins.create("myPlugin") {
206208
isJava = true // add generated code to the java source set
207209

208-
// add plugin options
210+
// Add plugin options
209211
options.put("myOption")
210212
options.put("myOption1", "myValue")
211213

@@ -229,7 +231,7 @@
229231
locator = "buf.build/grpc/go"
230232
}
231233

232-
// other Buf configuration options:
234+
// Additional Buf configuration options:
233235
strategy = ProtocPlugin.Strategy.All
234236
includeImports = false
235237
includeWkt = false
@@ -241,30 +243,30 @@
241243
Buf's plugin <a href="https://buf.build/docs/configuration/v2/buf-gen-yaml#plugins">configuration</a>
242244
options:
243245
</p>
244-
<list>
245-
<li>
246+
<deflist>
247+
<def title="strategy" id="strategy">
246248
<a href="https://buf.build/docs/configuration/v2/buf-gen-yaml/#strategy">strategy</a>
247249
— <code>All</code> or <code>Directory</code>
248-
</li>
249-
<li>
250+
</def>
251+
<def title="includeImports" id="includeImports">
250252
<a href="https://buf.build/docs/configuration/v2/buf-gen-yaml/#include_imports">includeImports</a>
251253
— <code>true</code> or <code>false</code>
252-
</li>
253-
<li>
254+
</def>
255+
<def title="includeWkt" id="includeWkt">
254256
<a href="https://buf.build/docs/configuration/v2/buf-gen-yaml/#include_wkt">includeWkt</a>
255257
— <code>true</code> or <code>false</code>
256-
</li>
257-
<li>
258+
</def>
259+
<def title="types" id="types">
258260
<a href="https://buf.build/docs/configuration/v2/buf-gen-yaml/#types">types</a>
259261
— a list of types to generate.
260-
</li>
261-
<li>
262+
</def>
263+
<def title="excludeTypes" id="excludeTypes">
262264
<a href="https://buf.build/docs/configuration/v2/buf-gen-yaml/#exclude-types">excludeTypes</a>
263265
— a list of types to exclude from generation.
264-
</li>
265-
</list>
266+
</def>
267+
</deflist>
266268
<p>
267-
A plugin, once added to the <code>protocPlugins</code> container, can be used in a source set:
269+
Once a plugin is added to the <code>protocPlugins</code> container, it can be used in a source set:
268270
</p>
269271
<code-block lang="Kotlin">
270272
protoSourceSets {
@@ -283,49 +285,49 @@
283285
</p>
284286
<note>
285287
We <b>don't</b> use Buf's <code>build.buf</code> Gradle Plugin
286-
and prohibit using it in projects with our plugin to prevent conflicts.
288+
and disallow using it in projects that apply our plugin, in order to avoid conflicts.
287289
</note>
288290
<chapter title="Generated Workspace" id="generated-workspace">
289291
<p>
290-
To make UX smooth, we introduce a concept of a <b>generated workspace</b>.
292+
To improve the developer experience, we introduce the concept of a <b>generated workspace</b>.
291293
It's a directory that contains all the necessary files for Buf to work:
292294
</p>
293295
<list>
294296
<li>
295-
Filtered <code>.proto</code> files
297+
Filtered <path>.proto</path> files
296298
</li>
297299
<li>
298-
Generated <code>buf.yaml</code> file
300+
Generated <path>buf.yaml</path> file
299301
</li>
300302
<li>
301-
Generated <code>buf.gen.yaml</code> file
303+
Generated <path>buf.gen.yaml</path> file
302304
</li>
303305
<li>
304306
Automatically managed imports from a <code>main</code> source set to a <code>test</code> source set,
305307
making imports intuitive.
306308
</li>
307309
</list>
308310
<p>
309-
This workspace is created automatically for each source set,
310-
and can be found in the <code>build/protoBuild</code> directory.
311+
This workspace is created automatically for each source set
312+
and can be found in the <path>build/protoBuild</path> directory.
311313
You don't need to do anything with it, unless you want to customise it.
312314
</p>
313315
</chapter>
314316
<chapter title="Tasks" id="buf-tasks">
315317
<p>
316-
We create the following tasks if the project is configured to use <code>grpc</code>:
318+
If your project is configured to use gRPC, the following tasks will be generated:
317319
</p>
318320
<list>
319321
<li>
320322
<code>generateBufYaml&lt;sourceSet&gt;</code>
321-
— generates <code>buf.yaml</code>
323+
— generates <path>buf.yaml</path>
322324
<br/>
323325
<br/>
324326
Type: <code>kotlinx.rpc.buf.tasks.GenerateBufYaml</code>
325327
</li>
326328
<li>
327329
<code>generateBufGenYaml&lt;sourceSet&gt;</code>
328-
— generates <code>buf.gen.yaml</code>
330+
— generates <path>buf.gen.yaml</path>
329331
<br/>
330332
<br/>
331333
Type: <code>kotlinx.rpc.buf.tasks.GenerateBufGenYaml</code>
@@ -359,12 +361,12 @@
359361
rpc {
360362
grpc {
361363
buf {
362-
// configure Buf here
364+
// Configure Buf
363365
logFormat = BufExtenstion.LogFormat.Text
364366
timeout = 60.seconds
365367

366368
generate {
367-
// configure Buf generate here
369+
// Configure Buf generate
368370

369371
includeImports = false
370372
includeWkt = false
@@ -377,51 +379,51 @@
377379
<p>
378380
General configuration options:
379381
</p>
380-
<list>
381-
<li>
382+
<deflist>
383+
<def title="logFormat" id="logFormat">
382384
<a href="https://buf.build/docs/reference/cli/buf/#log-format">logFormat</a>
383385
— either <code>Text</code>, <code>Color</code>, <code>Json</code> or <code>Default</code>
384-
</li>
385-
<li>
386+
</def>
387+
<def title="timeout" id="timeout">
386388
<a href="https://buf.build/docs/reference/cli/buf/#timeout">timeout</a>
387389
— timeout for the <code>buf</code> commands, always converted to whole seconds
388-
</li>
389-
<li>
390-
Gradle's <code>--debug</code> enables Buf's <code>--debug</code> option.
391-
</li>
392-
</list>
390+
</def>
391+
<def title="--debug" id="debug">
392+
Running Gradle with <code>--debug</code> enables Buf's <code>--debug</code> option as well.
393+
</def>
394+
</deflist>
393395
<p>
394396
<code>buf generate</code> configuration options:
395397
</p>
396-
<list>
397-
<li>
398+
<deflist>
399+
<def title="includeImports" id="generate_includeImports">
398400
<a href="https://buf.build/docs/reference/cli/buf/generate/#include-imports">includeImports</a>
399401
— <code>true</code> or <code>false</code>
400-
</li>
401-
<li>
402+
</def>
403+
<def title="includeWkt" id="generate_includeWkt">
402404
<a href="https://buf.build/docs/reference/cli/buf/generate/#include-wkt">includeWkt</a>
403405
— <code>true</code> or <code>false</code>
404-
</li>
405-
<li>
406+
</def>
407+
<def title="errorFormat" id="generate_errorFormat">
406408
<a href="https://buf.build/docs/reference/cli/buf/generate/#error-format">errorFormat</a>
407409
— either <code>Text</code>, <code>Json</code>, <code>Msvs</code>,
408410
<code>Junit</code>, <code>GithubActions</code> or <code>Default</code>
409-
</li>
410-
</list>
411+
</def>
412+
</deflist>
411413
</chapter>
412414
<chapter title="Custom tasks" id="buf-custom-tasks">
413415
<p>
414-
We only support <code>generate</code> tasks for now.
415-
But Buf has great capabilities for managing <code>.proto</code> files,
416-
like linting, detection of breaking changes, etc.
417-
So we made it possible to create custom buf tasks.
416+
Currently, we only support <code>generate</code> tasks.
417+
However, because of Buf's capabilities for managing <path>.proto</path> files,
418+
like linting and detection of breaking changes,
419+
we provide a way to create custom Buf tasks.
418420
</p>
419421
<p>
420-
To create a custom task, it must be a subclass of the <code>kotlinx.rpc.buf.tasks.BufExecTask</code>.
421-
It doesn't need to define a <code>@TaskAction</code>, just a set of arguments and a command to execute.
422+
To create a custom task, extend the <code>kotlinx.rpc.buf.tasks.BufExecTask</code> class.
423+
You don't need to define a <code>@TaskAction</code>; just a set of arguments and a command to execute.
422424
</p>
423425
<p>
424-
Registering the task can be done in two ways:
426+
You can register the task in two ways:
425427
</p>
426428
<list>
427429
<li>
@@ -443,8 +445,8 @@
443445
These tasks can be executed on a generated workspace for all proto source sets.
444446
</p>
445447
<note>
446-
Note that the tasks are not plugged into the build cycle,
447-
so they won't be executed automatically.
448+
These tasks are not plugged into the Gradle build cycle,
449+
so you must run them manually
448450
</note>
449451
</li>
450452
<li>
@@ -458,7 +460,7 @@
458460
}
459461
</code-block>
460462
<p>
461-
It is just a regular Gradle task that has access to the Buf's executable
463+
It is a standard Gradle task that has access to the Buf's executable
462464
and some predefined properties.
463465
</p>
464466
</li>

0 commit comments

Comments
 (0)