feat: Update Batch Operations API docs

backend/api/src/main/kotlin/io/tolgee/api/v2/controllers/batch/BatchJobManagementController.kt

@@ -33,7 +33,7 @@ import javax.validation.Valid
 @RestController
 @CrossOrigin(origins = ["*"])
 @RequestMapping(value = ["/v2/projects/{projectId:\\d+}/", "/v2/projects/"])
-@Tag(name = "Batch job management")
+@Tag(name = "Batch Operations management")
 @Suppress("SpringJavaInjectionPointsAutowiringInspection", "MVCPathVariableInspection")
 class BatchJobManagementController(
   private val batchJobCancellationManager: BatchJobCancellationManager,
@@ -47,7 +47,7 @@ class BatchJobManagementController(
   @GetMapping(value = ["batch-jobs"])
   @AccessWithApiKey()
   @AccessWithProjectPermission(Scope.BATCH_JOBS_VIEW)
-  @Operation(summary = "Lists all batch jobs in project")
+  @Operation(summary = "Lists all batch operations in project")
   fun list(@Valid @ParameterObject @SortDefault("id") pageable: Pageable): PagedModel<BatchJobModel> {
     val views = batchJobService.getViews(projectHolder.project.id, null, pageable)
     return pagedResourcesAssembler.toModel(views, batchJobModelAssembler)
@@ -56,7 +56,7 @@ class BatchJobManagementController(
   @GetMapping(value = ["my-batch-jobs"])
   @AccessWithApiKey()
   @AccessWithAnyProjectPermission()
-  @Operation(summary = "Lists all batch jobs in project started by current user")
+  @Operation(summary = "Lists all batch operations in project started by current user")
   fun myList(@Valid @ParameterObject @SortDefault("id") pageable: Pageable): PagedModel<BatchJobModel> {
     val views = batchJobService.getViews(
       projectId = projectHolder.project.id,
@@ -70,9 +70,9 @@ class BatchJobManagementController(
   @AccessWithApiKey()
   @AccessWithAnyProjectPermission()
   @Operation(
-    summary = "Returns all running and pending tasks. " +
-      "Completed tasks are returned only if they are not older than 1 hour. " +
-      "If user doesn't have permission to view all batch jobs, only their jobs are returned."
+    summary = "Returns all running and pending batch operations",
+    description = "Completed batch operations are returned only if they are not older than 1 hour. " +
+      "If user doesn't have permission to view all batch operations, only their operations are returned."
   )
   fun currentJobs(): CollectionModel<BatchJobModel> {
     val views = batchJobService.getCurrentJobViews(
@@ -84,7 +84,7 @@ class BatchJobManagementController(
   @GetMapping(value = ["batch-jobs/{id}"])
   @AccessWithApiKey()
   @AccessWithAnyProjectPermission()
-  @Operation(summary = "Returns the batch job")
+  @Operation(summary = "Returns batch operation")
   fun get(@PathVariable id: Long): BatchJobModel {
     val view = batchJobService.getView(id)
     checkViewPermission(view.batchJob)
@@ -94,7 +94,7 @@ class BatchJobManagementController(
   @PutMapping(value = ["batch-jobs/{id}/cancel"])
   @AccessWithApiKey()
   @AccessWithAnyProjectPermission()
-  @Operation(summary = "Stops batch job (if possible)")
+  @Operation(summary = "Stops batch operation (if possible)")
   fun cancel(@PathVariable id: Long) {
     checkCancelPermission(batchJobService.getJobDto(id))
     batchJobCancellationManager.cancel(id)

backend/api/src/main/kotlin/io/tolgee/api/v2/controllers/batch/StartBatchJobController.kt

@@ -34,7 +34,7 @@ import javax.validation.Valid
 @RestController
 @CrossOrigin(origins = ["*"])
 @RequestMapping(value = ["/v2/projects/{projectId:\\d+}/start-batch-job", "/v2/projects/start-batch-job"])
-@Tag(name = "Start batch jobs")
+@Tag(name = "Batch Operations")
 @Suppress("SpringJavaInjectionPointsAutowiringInspection", "MVCPathVariableInspection")
 class StartBatchJobController(
   private val securityService: SecurityService,
@@ -46,7 +46,10 @@ class StartBatchJobController(
   @PostMapping(value = ["/pre-translate-by-tm"])
   @AccessWithApiKey()
   @AccessWithProjectPermission(Scope.BATCH_PRE_TRANSLATE_BY_MT)
-  @Operation(summary = "Translates provided keys to provided languages")
+  @Operation(
+    summary = "Pre-translate by TM",
+    description = "Pre-translate provided keys to provided languages by TM."
+  )
   fun translate(@Valid @RequestBody data: PreTranslationByTmRequest): BatchJobModel {
     securityService.checkLanguageTranslatePermission(projectHolder.project.id, data.targetLanguageIds)
     securityService.checkKeyIdsExistAndIsFromProject(data.keyIds, projectHolder.project.id)
@@ -61,7 +64,10 @@ class StartBatchJobController(
   @PostMapping(value = ["/machine-translate"])
   @AccessWithApiKey()
   @AccessWithProjectPermission(Scope.BATCH_MACHINE_TRANSLATE)
-  @Operation(summary = "Translates provided keys to provided languages")
+  @Operation(
+    summary = "Machine Translation",
+    description = "Translate provided keys to provided languages through primary MT provider."
+  )
   fun machineTranslation(@Valid @RequestBody data: MachineTranslationRequest): BatchJobModel {
     securityService.checkLanguageTranslatePermission(projectHolder.project.id, data.targetLanguageIds)
     securityService.checkKeyIdsExistAndIsFromProject(data.keyIds, projectHolder.project.id)
@@ -76,7 +82,7 @@ class StartBatchJobController(
   @PostMapping(value = ["/delete-keys"])
   @AccessWithApiKey()
   @AccessWithProjectPermission(Scope.KEYS_DELETE)
-  @Operation(summary = "Translates provided keys to provided languages")
+  @Operation(summary = "Delete keys")
   fun deleteKeys(@Valid @RequestBody data: DeleteKeysRequest): BatchJobModel {
     securityService.checkKeyIdsExistAndIsFromProject(data.keyIds, projectHolder.project.id)
     return batchJobService.startJob(
@@ -105,7 +111,10 @@ class StartBatchJobController(
   @PostMapping(value = ["/clear-translations"])
   @AccessWithApiKey()
   @AccessWithProjectPermission(Scope.TRANSLATIONS_EDIT)
-  @Operation(summary = "Clear translation values")
+  @Operation(
+    summary = "Clear translation values",
+    description = "Clear translation values for provided keys in selected languages."
+  )
   fun clearTranslations(@Valid @RequestBody data: ClearTranslationsRequest): BatchJobModel {
     securityService.checkKeyIdsExistAndIsFromProject(data.keyIds, projectHolder.project.id)
     securityService.checkLanguageTranslatePermission(projectHolder.project.id, data.languageIds)
@@ -120,7 +129,10 @@ class StartBatchJobController(
   @PostMapping(value = ["/copy-translations"])
   @AccessWithApiKey()
   @AccessWithProjectPermission(Scope.TRANSLATIONS_EDIT)
-  @Operation(summary = "Clear translation values")
+  @Operation(
+    summary = "Copy translation values",
+    description = "Copy translation values from one language to other languages."
+  )
   fun copyTranslations(@Valid @RequestBody data: CopyTranslationRequest): BatchJobModel {
     securityService.checkKeyIdsExistAndIsFromProject(data.keyIds, projectHolder.project.id)
     securityService.checkLanguageTranslatePermission(projectHolder.project.id, data.targetLanguageIds)
@@ -136,7 +148,7 @@ class StartBatchJobController(
   @PostMapping(value = ["/tag-keys"])
   @AccessWithApiKey()
   @AccessWithProjectPermission(Scope.KEYS_EDIT)
-  @Operation(summary = "Tag keys")
+  @Operation(summary = "Add tags")
   fun tagKeys(@Valid @RequestBody data: TagKeysRequest): BatchJobModel {
     data.tags.validate()
     securityService.checkKeyIdsExistAndIsFromProject(data.keyIds, projectHolder.project.id)
@@ -151,7 +163,7 @@ class StartBatchJobController(
   @PostMapping(value = ["/untag-keys"])
   @AccessWithApiKey()
   @AccessWithProjectPermission(Scope.KEYS_EDIT)
-  @Operation(summary = "Tag keys")
+  @Operation(summary = "Remove tags")
   fun untagKeys(@Valid @RequestBody data: UntagKeysRequest): BatchJobModel {
     securityService.checkKeyIdsExistAndIsFromProject(data.keyIds, projectHolder.project.id)
     return batchJobService.startJob(
@@ -165,7 +177,7 @@ class StartBatchJobController(
   @PostMapping(value = ["/set-keys-namespace"])
   @AccessWithApiKey()
   @AccessWithProjectPermission(Scope.KEYS_EDIT)
-  @Operation(summary = "Tag keys")
+  @Operation(summary = "Set keys namespace")
   fun setKeysNamespace(@Valid @RequestBody data: SetKeysNamespaceRequest): BatchJobModel {
     securityService.checkKeyIdsExistAndIsFromProject(data.keyIds, projectHolder.project.id)
     return batchJobService.startJob(

backend/data/src/main/kotlin/io/tolgee/batch/BatchJobActivityFinalizer.kt

@@ -55,7 +55,10 @@ class BatchJobActivityFinalizer(
     waitFor(20000) {
       val committedChunks = batchJobStateProvider.get(job.id).values
         .count { it.retry == false && it.transactionCommitted && it.status.completed }
-      logger.debug("Waitinng for completed chunks ($committedChunks) to be equal to all other chunks count (${job.totalChunks - 1})")
+      logger.debug(
+        "Waiting for completed chunks ($committedChunks) to be equal to all other chunks" +
+          " count (${job.totalChunks - 1})"
+      )
       committedChunks == job.totalChunks - 1
     }
   }

backend/data/src/main/kotlin/io/tolgee/component/bucket/TokenBucketManager.kt

@@ -87,7 +87,10 @@ class TokenBucketManager(
   }
 
   fun setEmptyUntil(bucketId: String, refillAt: Long) {
-    logger.debug("Setting bucket $bucketId empty for next ${Duration.ofMillis(refillAt - currentDateProvider.date.time).seconds} seconds")
+    logger.debug(
+      "Setting bucket $bucketId empty for " +
+        "next ${Duration.ofMillis(refillAt - currentDateProvider.date.time).seconds} seconds"
+    )
     updateBucket(bucketId) { setEmptyUntilMappingFn(it, refillAt) }
   }