Merge pull request #1617 from 1c-syntax/l10n_develop

Author: nixel2007

docs/en/contributing/DiagnostcAddSettings.md

@@ -1,7 +1,7 @@
 # Adding parameters for diagnostic
 
-Some diagnostics may have parameters that allow end users to customize the algorithm.
- For example: the parameter can be the maximum string length for diagnostics for long strings or a list of numeric constants that are not magic numbers.
+Some diagnostics may have parameters that allow end users to customize the algorithm.  
+For example: the parameter can be the maximum string length for diagnostics for long strings or a list of numeric constants that are not magic numbers.
 
 ## Diagnostic parameter implementation
 
@@ -11,19 +11,20 @@ To implement the diagnostic parameter, you need to make changes to the diagnosti
 
 Add a constant field to the diagnostic class, in which the default value of the parameter will be saved. For example `private static final String DEFAULT_COMMENTS_ANNOTATION = "//@";`.
 
-It is necessary to add a private field in which the parameter value will be stored. The field needs to be annotated `@DiagnosticParameter` In the annotation, you must specify the type of the parameter and the default value (the value is always a string type).
- For example
+It is necessary to add a private field in which the parameter value will be stored. The field needs to be annotated `@DiagnosticParameter` In the annotation, you must specify the type of the parameter and the default value (the value is always a string type).  
+For example
 
 ```java
 @DiagnosticParameter(
     type = String.class,
     defaultValue = "" + DEFAULT_COMMENTS_ANNOTATION
   )
   private String commentsAnnotation = DEFAULT_COMMENTS_ANNOTATION;
+
 ```
 
-If the parameter is primitive or of type String and it is set by a simple setter, then that's it.
- If the parameter is "hard", for example, a pattern string for a regular expression that must be evaluated before setting, then you need to implement a method for setting parameter values `configure`.
+If the parameter is primitive or of type String and it is set by a simple setter, then that's it.  
+If the parameter is "hard", for example, a pattern string for a regular expression that must be evaluated before setting, then you need to implement a method for setting parameter values `configure`.
 
 For example, there are two parameters:
 
@@ -43,14 +44,15 @@ Then the method of setting the parameter values will look:
       (String) configuration.getOrDefault("excludeMethods", EXCLUDE_METHODS_DEFAULT);
     this.excludeMethods = new ArrayList<>(Arrays.asList(excludeMethodsString.split(",")));
   }
+
 ```
 
 ### Test change
 
-It is necessary to add a test to change the diagnostic settings.
- The test is added to the diagnostic test class *(a separate method for each combination of diagnostic setting options)*. At the beginning of the test, you need to set the value of the diagnostic parameter, the subsequent steps are similar to the general rules for writing tests.
- Для установки параметра диагностики из теста необходимо получить конфигурацию диагностики по умолчанию, используя метод `getDefaultConfiguration()` from the metadata of the current diagnostic `diagnosticInstance.getInfo()`. The next step is to change the parameter value by adding to the configuration collection, and then reconfigure using the method `configure`.
- Example
+It is necessary to add a test to change the diagnostic settings.  
+The test is added to the diagnostic test class _(a separate method for each combination of diagnostic setting options)_. At the beginning of the test, you need to set the value of the diagnostic parameter, the subsequent steps are similar to the general rules for writing tests.  
+To set a diagnostic parameter from a test, you need to get the default diagnostic configuration using the method `getDefaultConfiguration()` from the metadata of the current diagnostic `diagnosticInstance.getInfo()`. The next step is to change the parameter value by adding to the configuration collection, and then reconfigure using the method `configure`.  
+Example
 
 ```java
 // get current configuration
@@ -61,13 +63,14 @@ configuration.put("commentsAnnotation", "//(с)");
 
 // reconfiguring
 diagnosticInstance.configure(configuration);
+
 ```
 
 ### Adding a Parameter Description
 
-For correct operation, it is necessary to add a parameter description for each language in the diagnostic resource files.
- Diagnostic resources are located in files`resources/com/github/_1c_syntax/bsl/languageserver/diagnostics/<DIAGNOSTIC_KEY>_en.properties` and `resources/com/github/_1c_syntax/bsl/languageserver/diagnostics/<DIAGNOSTIC_KEY>_ru.properties`.
-In each file you need to add a new line with the name of the parameter and its description
+For correct operation, it is necessary to add a parameter description for each language in the diagnostic resource files.  
+Diagnostic resources are located in files`resources/com/github/_1c_syntax/bsl/languageserver/diagnostics/<DIAGNOSTIC_KEY>_en.properties` and `resources/com/github/_1c_syntax/bsl/languageserver/diagnostics/<DIAGNOSTIC_KEY>_ru.properties`.  
+In each file, add a new line with the parameter name and description
 
 ```ini
 commentsAnnotation=Skip annotation comments starting with the specified substrings. A comma separated list. For example: //@,//(c)

docs/en/contributing/DiagnosticDevWorkFlow.md

@@ -1,39 +1,34 @@
 # Diagnostic development workflow
 
-1. Go to the section [issues](https://github.com/1c-syntax/bsl-language-server/issues) and select your task from the list.  It is necessary to choose tasks that do not have an executor, i.e. `Assignees` is not specified (the block is on the right, almost under the heading).
-
-    1. If there is no task for diagnostics, then you need to create it by clicking the `New issue` button
-
+1. Go to the section [issues](https://github.com/1c-syntax/bsl-language-server/issues) and select your task from the list. It is necessary to choose tasks that do not have an executor, i.e. `Assignees` is not specified (the block is on the right, almost under the heading).
+   1. If there is no task for diagnostics, then you need to create it by clicking the `New issue` button
 2. Write in the comments to the task to the maintainers that you want to take the task to work. After your nickname appears in the task in the `Assignees` block, you can proceed.
-
 3. You need to create a fork of the repository in `GitHub`, clone the repository to your computer and create a new feature branch (development by git flow).
-
-    1. If the fork has already been created earlier, then you need to update the `develop` branch from the primary repository. The easiest way to do this is as follows
-        1. The local repository has two remote repository addresses: yours and primary
-        2.  Get updates from both repositories `git fetch --progress "--all" --prune`
-        3.  In the local repository, switch to the branch `develop`
-        4.  Reset the branch state to the state of the primary repository (`git reset --hard`)
-        5. Pushin the branch to your remote repository
-
-4. To create all the necessary files in the right places, you need to run the command `gradlew newDiagnostic --key="KeyDiagnostic"`, instead `KeyDiagnostic`  you must specify the key of your diagnostic. Details in help `gradlew -q help --task newDiagnostic`. Parameters:
-
-    - `--key` - Diagnostic key
-    - `--nameRu` - Russian description
-    - `--nameEn` - English description
+   1. If the fork has already been created earlier, then you need to update the `develop` branch from the primary repository. The easiest way to do this is as follows
+      1. The local repository has two remote repository addresses: yours and primary
+      2. Get updates from both repositories `git fetch --progress "--all" --prune`
+      3. In the local repository, switch to the branch `develop`
+      4. Reset the branch state to the state of the primary repository (`git reset --hard`)
+      5. Pushin the branch to your remote repository
+4. To create all the necessary files in the right places, you need to run the command `gradlew newDiagnostic --key="KeyDiagnostic"`, instead `KeyDiagnostic` you must specify the key of your diagnostic. Details in help `gradlew -q help --task newDiagnostic`. Parameters:
+
+   * `--key` - Diagnostic key
+   * `--nameRu` - Russian description
+   * `--nameEn` - English description
 
 At startup, a list of available diagnostic tags is displayed. You must enter 1-3 tags from the space separated ones.
 
-1. To develop
-2. After completion of the development of diagnostics: it is necessary to check the changes (after testing), and also perform a number of service tasks.
-     To simplify, a special command has been created that can be run in the console `gradlew precommit` or from the Gradle taskbar `precommit`. Task actions:
+5. To develop
+6. After completion of the development of diagnostics: it is necessary to check the changes (after testing), and also perform a number of service tasks.  
+   To simplify, a special command has been created that can be run in the console `gradlew precommit` or from the Gradle taskbar `precommit`. Task includes subtasks
 
 - test - autotesting project
 - licenseFormat - installation of a license block in java source files
 - updateDiagnosticDocs - diagnostic help update
 - updateDiagnosticIndex - diagnostic index update
 - updateJsonSchema - json schema update
 
-1. If everything is done correctly, you need to commit the changes and push to your remote repository.
-2. You need to create `Pull request` from your feature branch to the `develop` branch of the primary repository and fill in the information in the description.
-3. Before closing `Pull request`, the maintainers will conduct a Code review. Correction of errors must be done in the same feature branch, GitHub will automatically add changes to the created `Pull request`.
-4. Closing `Pull request` confirms the completion of the task.
+7. If everything is done correctly, you need to commit the changes and push to your remote repository.
+8. You need to create `Pull request` from your feature branch to the `develop` branch of the primary repository and fill in the information in the description.
+9. Before closing `Pull request`, the maintainers will conduct a Code review. Correction of errors must be done in the same feature branch, GitHub will automatically add changes to the created `Pull request`.
+10. Closing `Pull request` confirms the completion of the task.