Skip to content

Commit 6bafc2c

Browse files
pwrobeldevpwrobeldev
authored
Validation: warn when unnamed parameters are documented for lambdas (#1768)
When we do not specify lambda parameter names then 'p0, p1 ... pN' are used. Such names do not bring any context for the caller to understand their purpose. Moreover, when such parameters are explicitly documented it is usually a mistake. Therefore, 'LimeLambdaValidator' class is extended to print warning or error (depending on 'werror' flag) when parameters without custom names are explicitly documented for lambdas. Signed-off-by: Patryk Wrobel <183546751+pwrobeldev@users.noreply.github.com>
1 parent e8d6df5 commit 6bafc2c

3 files changed

Lines changed: 145 additions & 8 deletions

File tree

‎CHANGELOG.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,9 @@
11
# Gluecodium project Release Notes
22

3+
## Unreleased
4+
### Features:
5+
* Validation: `LimeLambdaValidator` class is extended with new functionality to raise warning/error when parameters with default names are explicitly documented.
6+
37
## 13.16.0
48
Release date 2025-06-13
59
### Features:

‎gluecodium/src/main/java/com/here/gluecodium/validator/LimeLambdaValidator.kt‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -57,18 +57,26 @@ class LimeLambdaValidator(private val logger: LimeLogger, generatorOptions: Gene
5757
}
5858

5959
private fun validateLambdaDocs(limeLambda: LimeLambda): Boolean {
60-
val checkDocsMessage = "please check $LAMBDAS_STRUCTURED_COMMENTS"
60+
val checkCommentsDocsMessage = "please check $LAMBDAS_STRUCTURED_COMMENTS"
61+
val checkNamedParamsSyntax = "please check $LAMBDAS_NAMED_PARAMS_SYNTAX"
6162
var result = true
6263

6364
for (parameter in limeLambda.parameters) {
6465
if (parameter.comment.isEmpty()) {
65-
logger.maybeError(limeLambda, "Parameter '${parameter.name}' must be documented; $checkDocsMessage")
66+
logger.maybeError(limeLambda, "Parameter '${parameter.name}' must be documented; $checkCommentsDocsMessage")
67+
result = false
68+
} else if (!parameter.isNamedParameter) {
69+
logger.maybeError(
70+
limeLambda,
71+
"Default parameter name '${parameter.name}' is documented. Please set an explicit name for documented parameters; " +
72+
checkNamedParamsSyntax,
73+
)
6674
result = false
6775
}
6876
}
6977

7078
if (!limeLambda.returnType.isVoid && limeLambda.returnType.comment.isEmpty()) {
71-
logger.maybeError(limeLambda, "Return must be documented; $checkDocsMessage")
79+
logger.maybeError(limeLambda, "Return must be documented; $checkCommentsDocsMessage")
7280
result = false
7381
}
7482

@@ -77,5 +85,6 @@ class LimeLambdaValidator(private val logger: LimeLogger, generatorOptions: Gene
7785

7886
companion object {
7987
private const val LAMBDAS_STRUCTURED_COMMENTS = "$LIME_MARKDOWN_DOCS#structured-comments-for-lambdas"
88+
private const val LAMBDAS_NAMED_PARAMS_SYNTAX = "https://github.com/heremaps/gluecodium/blob/master/docs/lime_idl.md#lambda"
8089
}
8190
}

‎gluecodium/src/test/java/com/here/gluecodium/validator/LimeLambdaValidatorDocsTest.kt‎

Lines changed: 129 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -19,6 +19,7 @@
1919

2020
package com.here.gluecodium.validator
2121

22+
import com.here.gluecodium.common.LimeLogger
2223
import com.here.gluecodium.generator.common.GeneratorOptions
2324
import com.here.gluecodium.model.lime.LimeAttributeType
2425
import com.here.gluecodium.model.lime.LimeAttributes
@@ -31,7 +32,9 @@ import com.here.gluecodium.model.lime.LimeModel
3132
import com.here.gluecodium.model.lime.LimePath
3233
import com.here.gluecodium.model.lime.LimeReturnType
3334
import com.here.gluecodium.model.lime.LimeStruct
35+
import io.mockk.justRun
3436
import io.mockk.mockk
37+
import io.mockk.verify
3538
import org.junit.Assert.assertFalse
3639
import org.junit.Assert.assertTrue
3740
import org.junit.Test
@@ -54,7 +57,14 @@ class LimeLambdaValidatorDocsTest {
5457
path = lambdaPath,
5558
comment = limeComment,
5659
returnType = LimeReturnType(typeRef = LimeBasicTypeRef.INT, comment = LimeComment("Important integer")),
57-
parameters = listOf(LimeLambdaParameter(path = lambdaPath.child("param1"), typeRef = LimeBasicTypeRef.FLOAT)),
60+
parameters =
61+
listOf(
62+
LimeLambdaParameter(
63+
path = lambdaPath.child("param1"),
64+
isNamedParameter = true,
65+
typeRef = LimeBasicTypeRef.FLOAT,
66+
),
67+
),
5868
)
5969
allElements[lambdaPath.toString()] = limeLambda
6070

@@ -75,7 +85,14 @@ class LimeLambdaValidatorDocsTest {
7585
path = lambdaPath,
7686
comment = limeComment,
7787
returnType = LimeReturnType(typeRef = LimeBasicTypeRef.INT, comment = LimeComment("Important integer")),
78-
parameters = listOf(LimeLambdaParameter(path = lambdaPath.child("param1"), typeRef = LimeBasicTypeRef.FLOAT)),
88+
parameters =
89+
listOf(
90+
LimeLambdaParameter(
91+
path = lambdaPath.child("param1"),
92+
isNamedParameter = true,
93+
typeRef = LimeBasicTypeRef.FLOAT,
94+
),
95+
),
7996
)
8097
allElements[lambdaPath.toString()] = limeLambda
8198

@@ -164,11 +181,13 @@ class LimeLambdaValidatorDocsTest {
164181
listOf(
165182
LimeLambdaParameter(
166183
path = lambdaPath.child("param1"),
184+
isNamedParameter = true,
167185
typeRef = LimeBasicTypeRef.FLOAT,
168186
comment = LimeComment("Some param"),
169187
),
170188
LimeLambdaParameter(
171189
path = lambdaPath.child("param2"),
190+
isNamedParameter = true,
172191
typeRef = LimeBasicTypeRef.FLOAT,
173192
comment = LimeComment("Another param"),
174193
),
@@ -196,7 +215,14 @@ class LimeLambdaValidatorDocsTest {
196215
comment = limeComment,
197216
attributes = attributes,
198217
returnType = LimeReturnType(typeRef = LimeBasicTypeRef.INT, comment = LimeComment("Important integer")),
199-
parameters = listOf(LimeLambdaParameter(path = lambdaPath.child("param1"), typeRef = LimeBasicTypeRef.FLOAT)),
218+
parameters =
219+
listOf(
220+
LimeLambdaParameter(
221+
path = lambdaPath.child("param1"),
222+
isNamedParameter = true,
223+
typeRef = LimeBasicTypeRef.FLOAT,
224+
),
225+
),
200226
)
201227
allElements[lambdaPath.toString()] = limeLambda
202228

@@ -219,7 +245,14 @@ class LimeLambdaValidatorDocsTest {
219245
path = lambdaPath,
220246
comment = limeComment,
221247
returnType = LimeReturnType(typeRef = LimeBasicTypeRef.INT, comment = LimeComment("Important integer")),
222-
parameters = listOf(LimeLambdaParameter(path = lambdaPath.child("param1"), typeRef = LimeBasicTypeRef.FLOAT)),
248+
parameters =
249+
listOf(
250+
LimeLambdaParameter(
251+
path = lambdaPath.child("param1"),
252+
isNamedParameter = true,
253+
typeRef = LimeBasicTypeRef.FLOAT,
254+
),
255+
),
223256
)
224257

225258
val attributes = LimeAttributes.Builder().addAttribute(LimeAttributeType.INTERNAL).build()
@@ -248,7 +281,14 @@ class LimeLambdaValidatorDocsTest {
248281
path = lambdaPath,
249282
comment = limeComment,
250283
returnType = LimeReturnType(typeRef = LimeBasicTypeRef.INT, comment = LimeComment("Important integer")),
251-
parameters = listOf(LimeLambdaParameter(path = lambdaPath.child("param1"), typeRef = LimeBasicTypeRef.FLOAT)),
284+
parameters =
285+
listOf(
286+
LimeLambdaParameter(
287+
path = lambdaPath.child("param1"),
288+
isNamedParameter = true,
289+
typeRef = LimeBasicTypeRef.FLOAT,
290+
),
291+
),
252292
)
253293

254294
val nestedStruct = LimeStruct(path = nestedStructPath, lambdas = listOf(limeLambda))
@@ -267,4 +307,88 @@ class LimeLambdaValidatorDocsTest {
267307
// Then docs validation passes (for lambdas from types nested in internal ones it is skipped).
268308
assertTrue(result)
269309
}
310+
311+
@Test
312+
fun validateDocumentationCommentForUnnamedParameterWhenWerrorIsEnabled() {
313+
// Given LimeLambda with parameter with default name that is documented.
314+
val lambdaPath = LimePath(listOf(), listOf("SomeLambda"))
315+
val parameter =
316+
LimeLambdaParameter(
317+
path = lambdaPath.child("p0"),
318+
comment = LimeComment("Some unnamed param"),
319+
isNamedParameter = false,
320+
typeRef = LimeBasicTypeRef.FLOAT,
321+
)
322+
323+
val limeLambda =
324+
LimeLambda(
325+
path = lambdaPath,
326+
comment = limeComment,
327+
returnType = LimeReturnType(typeRef = LimeBasicTypeRef.INT, comment = LimeComment("Important integer")),
328+
parameters = listOf(parameter),
329+
)
330+
allElements[lambdaPath.toString()] = limeLambda
331+
332+
// When validating it with werror flag enabled.
333+
val logger: LimeLogger = mockk()
334+
justRun { logger.error(limeLambda, any()) }
335+
336+
val validator = LimeLambdaValidator(logger = logger, generatorOptions = generatorOptions)
337+
val result = validator.validate(limeModel)
338+
339+
// Then validation fails.
340+
verify(exactly = 1) {
341+
logger.error(
342+
limeLambda,
343+
match {
344+
it.startsWith(
345+
"Default parameter name '${parameter.name}' is documented. Please set an explicit name for documented parameters;",
346+
)
347+
},
348+
)
349+
}
350+
assertFalse(result)
351+
}
352+
353+
@Test
354+
fun validateDocumentationCommentForUnnamedParameterWhenWerrorIsDisabled() {
355+
// Given LimeLambda with parameter with default name that is documented.
356+
val lambdaPath = LimePath(listOf(), listOf("SomeLambda"))
357+
val parameter =
358+
LimeLambdaParameter(
359+
path = lambdaPath.child("p0"),
360+
comment = LimeComment("Some unnamed param"),
361+
isNamedParameter = false,
362+
typeRef = LimeBasicTypeRef.FLOAT,
363+
)
364+
365+
val limeLambda =
366+
LimeLambda(
367+
path = lambdaPath,
368+
comment = limeComment,
369+
returnType = LimeReturnType(typeRef = LimeBasicTypeRef.INT, comment = LimeComment("Important integer")),
370+
parameters = listOf(parameter),
371+
)
372+
allElements[lambdaPath.toString()] = limeLambda
373+
374+
// When validating it with werror flag disabled.
375+
val logger: LimeLogger = mockk()
376+
justRun { logger.warning(limeLambda, any()) }
377+
378+
val validator = LimeLambdaValidator(logger = logger)
379+
val result = validator.validate(limeModel)
380+
381+
// Then validation succeeds with warning.
382+
verify(exactly = 1) {
383+
logger.warning(
384+
limeLambda,
385+
match {
386+
it.startsWith(
387+
"Default parameter name '${parameter.name}' is documented. Please set an explicit name for documented parameters;",
388+
)
389+
},
390+
)
391+
}
392+
assertTrue(result)
393+
}
270394
}

0 commit comments

Comments
 (0)