📝 Add docstrings to feature/updCommonLib

Docstrings generation was requested by @theshadowco.

* #524 (comment)

The following files were modified:

* `src/main/java/com/github/_1c_syntax/bsl/mdclasses/CF.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdclasses/MDClasses.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/Catalog.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/ChartOfCharacteristicTypes.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/Enum.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/Language.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/storage/form/FormElementType.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/ApplicationRunMode.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/AutoRecordType.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/ConfigurationExtensionPurpose.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/DataLockControlMode.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/DataSeparation.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/DataSetType.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/FormType.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/Handler.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/IndexingType.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/InterfaceCompatibilityMode.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/MessageDirection.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/ObjectBelonging.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/ReturnValueReuse.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/ReuseSessions.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/RoleRight.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/TemplateType.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/TransferDirection.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/UseMode.java`
* `src/main/java/com/github/_1c_syntax/bsl/mdo/support/UsePurposes.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/common/context/MDCReaderContext.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/common/converter/DataSetConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/common/converter/EnumConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/common/converter/SubsystemConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/common/converter/ValueTypeConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/common/converter/ValueTypeDescriptionConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/common/converter/ValueTypeQualifierConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/common/xstream/ExtendXStream.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/designer/DesignerReader.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/designer/converter/FormElementConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/designer/converter/MDChildConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/designer/converter/TemplateConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/edt/EDTReader.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/edt/converter/ExternalDataSourceTableConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/edt/converter/FormItemConverter.java`
* `src/main/java/com/github/_1c_syntax/bsl/reader/edt/converter/ObjectTemplateConverter.java`
* `src/test/java/com/github/_1c_syntax/bsl/test_utils/MDTestUtils.java`

Author: coderabbitai[bot]

src/main/java/com/github/_1c_syntax/bsl/mdclasses/CF.java

@@ -146,14 +146,11 @@ default List<Subsystem> includedSubsystems(MD md, boolean addParentSubsystem) {
   }
 
   /**
-   * Возвращает список подсистем, в состав которых входит ссылка
+   * List subsystems that include the specified metadata reference.
    *
-   * @param mdoReference       ссылка на объект метаданных
-   * @param addParentSubsystem - признак необходимости добавлять родительскую (текущую) подсистему в список,
-   *                           если объект присутствует в дочерних.
-   *                           Используется для кейса: раз есть в дочерней, то считаем что и ко всем родителям
-   *                           тоже относится
-   * @return список подсистем
+   * @param mdoReference       the metadata object reference to search for
+   * @param addParentSubsystem if true, include parent (containing) subsystems when the reference is present in a child subsystem
+   * @return a list of subsystems that include the given reference (may be empty)
    */
   default List<Subsystem> includedSubsystems(MdoReference mdoReference, boolean addParentSubsystem) {
     return getSubsystems().parallelStream()
@@ -196,4 +193,4 @@ default Optional<MD> findChild(MdoReference ref) {
   default Optional<CommonModule> findCommonModule(String name) {
     return Optional.ofNullable(getCommonModulesByName().get(name));
   }
-}
+}

src/main/java/com/github/_1c_syntax/bsl/mdclasses/MDClasses.java

@@ -190,6 +190,13 @@ private List<Path> findFiles(Path sourcePath, Pattern pattern) {
     return listPath;
   }
 
+  /**
+   * Collects the group names of MDO types to be used for exclusion filters.
+   *
+   * <p>Excludes the EXTERNAL_REPORT, EXTERNAL_DATA_PROCESSOR, and UNKNOWN types.</p>
+   *
+   * @return a set of group-name strings for all included MDOType values
+   */
   private Set<String> mdoTypeGroupNames() {
     return Arrays.stream(MDOType.values())
       .filter(type -> type != MDOType.EXTERNAL_REPORT
@@ -199,4 +206,4 @@ private Set<String> mdoTypeGroupNames() {
       .map(MDOType::groupName)
       .collect(Collectors.toSet());
   }
-}
+}

src/main/java/com/github/_1c_syntax/bsl/mdo/Catalog.java

@@ -109,6 +109,11 @@ public class Catalog implements ReferenceObject, AccessRightsOwner {
   @Singular("addOwners")
   List<MdoReference> owners;
 
+  /**
+   * Retrieve the catalog's child metadata objects.
+   *
+   * @return the list of child MD objects for this catalog, computed on first access and cached for subsequent calls
+   */
   @Override
   public List<MD> getChildren() {
     return children.getOrCompute();
@@ -190,4 +195,4 @@ private static List<RoleRight> computePossibleRights() {
       RoleRight.SWITCH_TO_DATA_HISTORY_VERSION
     );
   }
-}
+}

src/main/java/com/github/_1c_syntax/bsl/mdo/ChartOfCharacteristicTypes.java

@@ -161,12 +161,22 @@ private List<MD> computePlainStorageFields() {
     return LazyLoader.computePlainStorageFields(this);
   }
 
+  /**
+   * Compute the complete list of modules associated with this chart of characteristic types.
+   *
+   * @return the list of all modules that apply to this object, possibly empty
+   */
   private List<Module> computeAllModules() {
     return LazyLoader.computeAllModules(this);
   }
 
+  /**
+   * Gets the value type description for this chart of characteristic types.
+   *
+   * @return the ValueTypeDescription describing this object's value type
+   */
   @Override
   public ValueTypeDescription getValueType() {
     return type;
   }
-}
+}

src/main/java/com/github/_1c_syntax/bsl/mdo/Enum.java

@@ -134,13 +134,23 @@ public List<Module> getAllModules() {
     return allModules.getOrCompute();
   }
 
+  /**
+   * Compute the list of all modules associated with this Enum.
+   *
+   * @return a list of Module objects representing all modules belonging to this Enum; empty list if there are none
+   */
   private List<Module> computeAllModules() {
     return LazyLoader.computeAllModules(this);
   }
 
+  /**
+   * Returns the list of attributes declared on this enum.
+   *
+   * @return the list of attributes for this enum
+   */
   @Override
   public List<Attribute> getAllAttributes() {
     return getAttributes();
   }
 
-}
+}

src/main/java/com/github/_1c_syntax/bsl/mdo/Language.java

@@ -95,6 +95,13 @@ public static Language defaultLanguage() {
     return defaultLanguage(ScriptVariant.RUSSIAN);
   }
 
+  /**
+   * Creates a Language instance with the provided display name and language code.
+   *
+   * @param name the display name of the language
+   * @param code the language code used for synonym and languageCode fields
+   * @return a Language configured with the given name and code; synonym is initialized and mdoReference is configured for MDOType.LANGUAGE
+   */
   private static Language newLanguage(String name, String code) {
     return Language.builder()
       .name(name)
@@ -107,4 +114,4 @@ private static Language newLanguage(String name, String code) {
       .languageCode(code)
       .build();
   }
-}
+}

src/main/java/com/github/_1c_syntax/bsl/mdo/storage/form/FormElementType.java

@@ -84,15 +84,21 @@ public enum FormElementType implements EnumWithName {
   @Accessors(fluent = true)
   private final MultiName fullName;
 
+  /**
+   * Initializes the enum constant with localized display names.
+   *
+   * @param nameEn the English display name for the element
+   * @param nameRu the Russian display name for the element
+   */
   FormElementType(String nameEn, String nameRu) {
     this.fullName = MultiName.create(nameEn, nameRu);
   }
 
   /**
-   * Ищет элемент перечисления по именам (рус, анг)
+   * Finds a FormElementType by its English or Russian name.
    *
-   * @param string Имя искомого элемента
-   * @return Найденное значение, если не найден - то UNKNOWN
+   * @param string the English or Russian name to look up (case-insensitive)
+   * @return the matching FormElementType, or {@code UNKNOWN} if no match is found; a warning is logged when no match is found
    */
   public static FormElementType valueByName(String string) {
     var result = KEYS.getOrDefault(string.toLowerCase(Locale.ROOT), UNKNOWN);
@@ -101,4 +107,4 @@ public static FormElementType valueByName(String string) {
     }
     return result;
   }
-}
+}

src/main/java/com/github/_1c_syntax/bsl/mdo/support/ApplicationRunMode.java

@@ -46,17 +46,23 @@ public enum ApplicationRunMode implements EnumWithName {
   @Accessors(fluent = true)
   private final MultiName fullName;
 
+  /**
+   * Create an ApplicationRunMode with the given English and Russian display names.
+   *
+   * @param nameEn the English name for the mode
+   * @param nameRu the Russian name for the mode
+   */
   ApplicationRunMode(String nameEn, String nameRu) {
     this.fullName = MultiName.create(nameEn, nameRu);
   }
 
   /**
-   * Ищет элемент перечисления по именам (рус, анг)
+   * Finds an ApplicationRunMode by its English or Russian name (case-insensitive).
    *
-   * @param string Имя искомого элемента
-   * @return Найденное значение, если не найден - то UNKNOWN
+   * @param string English or Russian name of the mode to look up
+   * @return the matching ApplicationRunMode, or UNKNOWN if no match is found
    */
   public static ApplicationRunMode valueByName(String string) {
     return KEYS.getOrDefault(string.toLowerCase(Locale.ROOT), UNKNOWN);
   }
-}
+}

src/main/java/com/github/_1c_syntax/bsl/mdo/support/AutoRecordType.java

@@ -45,18 +45,24 @@ public enum AutoRecordType implements EnumWithName {
   @Accessors(fluent = true)
   private final MultiName fullName;
 
+  /**
+   * Creates an enum constant with the given English and Russian display names.
+   *
+   * @param nameEn the English name for the enum constant
+   * @param nameRu the Russian name for the enum constant
+   */
   AutoRecordType(String nameEn, String nameRu) {
     this.fullName = MultiName.create(nameEn, nameRu);
   }
 
 
-  /**
-   * Ищет элемент перечисления по именам (рус, анг)
-   *
-   * @param string Имя искомого элемента
-   * @return Найденное значение, если не найден - то UNKNOWN
+  /**
+   * Finds the enum constant matching the given English or Russian name (case-insensitive).
+   *
+   * @param string the name to look up (English or Russian, case-insensitive)
+   * @return the matching {@code AutoRecordType}, or {@code UNKNOWN} if no match is found
    */
   public static AutoRecordType valueByName(String string) {
     return KEYS.getOrDefault(string.toLowerCase(Locale.ROOT), UNKNOWN);
   }
-}
+}

src/main/java/com/github/_1c_syntax/bsl/mdo/support/ConfigurationExtensionPurpose.java

@@ -47,17 +47,25 @@ public enum ConfigurationExtensionPurpose implements EnumWithName {
   @Accessors(fluent = true)
   private final MultiName fullName;
 
+  /**
+   * Creates an enum constant with the specified English and Russian names.
+   *
+   * @param nameEn the English name for the enum constant
+   * @param nameRu the Russian name for the enum constant
+   */
   ConfigurationExtensionPurpose(String nameEn, String nameRu) {
     this.fullName = MultiName.create(nameEn, nameRu);
   }
 
-  /**
-   * Ищет элемент перечисления по именам (рус, анг)
-   *
-   * @param string Имя искомого элемента
-   * @return Найденное значение, если не найден - то UNKNOWN
+  /**
+   * Finds an enum constant by its English or Russian name.
+   *
+   * <p>Lookup is case-insensitive (uses Locale.ROOT).</p>
+   *
+   * @param string the English or Russian name to look up
+   * @return `UNKNOWN` if no match is found, otherwise the matching enum constant
    */
   public static ConfigurationExtensionPurpose valueByName(String string) {
     return KEYS.getOrDefault(string.toLowerCase(Locale.ROOT), UNKNOWN);
   }
-}
+}