google / google/protobuf-gradle-plugin
Documentation unclear on groovy/kotlin-stl distinction
- Dominant language
- Groovy
- Stars
- 1.8k
- Forks
- 288
- PR merge metrics
- No merged PRs in 30d
Description
The readme examples start with separate examples for groovy and kotlin-dsl to add the plugin to your project. However the kotlin-dsl example is no longer current, the rest of the document does not have consistent support for kotlin-dsl and it is not clear what is applicable to kotlin-dsl. The samples are better but also not at the latest version and less accessible to people searching for answers.
For example, to get android output with protobuf 3.8.0 and higher the following example given is:
```
dependencies {
// You need to depend on the lite runtime library, not protobuf-java
compile 'com.google.protobuf:protobuf-javalite:3.8.0'
}
protobuf {
protoc {
artifact = 'com.google.protobuf:protoc:3.8.0'
}
generateProtoTasks {
all().each { task ->
task.builtins {
java {
option "lite"
}
}
}
}
}
```
however, using kotlin-dsl this will not compile and the actual working code looks like this:
```
dependencies {
// protobuf
implementation("com.google.protobuf:protobuf-javalite:3.11.1")
}
protobuf {
protoc {
artifact = "com.google.protobuf:protoc:3.11.2"
}
generateProtoTasks {
all().forEach{
it.builtins{
id("java"){
option("lite")
}
}
}
}
}
```
The current 'adding the plugin' kotlin-dsl example:
```
plugins {
id "com.google.protobuf" version "0.8.11"
id "java"
}
```
Actually working version:
```
plugins {
id("com.android.application")
id("com.google.protobuf").version("0.8.11")
}
```
Translating between the two is frustrating as it is unclear what needs to be changed and finding the right method calls can be not so straightforward. Extending the readme to completely cover both (groovy and kotlin-dsl) cases and labeling specific sections and code snippets would make the docs much clearer. It would also make it much easier to use kotlin-dsl and would actually make the readme a great learning resource for kotlin-dsl as you have both groovy and kotlin-dsl next to each other for relatively complicated tasks.
Contributor guide
Research direction
Start with the README examples for adding the plugin and configuring protobuf generation. Compare the Groovy and kotlin-dsl snippets, update the outdated examples and versions shown in the issue, and label sections so readers can tell which syntax applies to each DSL. Done means both sets of examples are current, consistent, and usable for the documented Android output case.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- groovy, kotlin
- Domain
- build-system, documentation
- Issue type
- Documentation
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100