📝 Add docstrings to feature/546

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

@@ -0,0 +1,83 @@
+/*
+ * This file is a part of MDClasses.
+ *
+ * Copyright (c) 2019 - 2025
+ * Tymko Oleg <[email protected]>, Maximov Valery <[email protected]> and contributors
+ *
+ * SPDX-License-Identifier: LGPL-3.0-or-later
+ *
+ * MDClasses is free software; you can redistribute it and/or
+ * modify it under the terms of the GNU Lesser General Public
+ * License as published by the Free Software Foundation; either
+ * version 3.0 of the License, or (at your option) any later version.
+ *
+ * MDClasses is distributed in the hope that it will be useful,
+ * but WITHOUT ANY WARRANTY; without even the implied warranty of
+ * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
+ * Lesser General Public License for more details.
+ *
+ * You should have received a copy of the GNU Lesser General Public
+ * License along with MDClasses.
+ */
+package com.github._1c_syntax.bsl.mdo.support;
+
+import java.util.Locale;
+import java.util.Map;
+
+import com.github._1c_syntax.bsl.types.EnumWithName;
+import com.github._1c_syntax.bsl.types.MultiName;
+
+import lombok.Getter;
+import lombok.ToString;
+import lombok.experimental.Accessors;
+
+/**
+ * Серия кодов справочника.
+ * Определяет область действия уникальности кода справочника.
+ */
+@ToString(of = "fullName")
+public enum CodeSeries implements EnumWithName {
+  /**
+   * Весь справочник - уникальность кода проверяется во всем справочнике
+   */
+  WHOLE_CATALOG("WholeCatalog", "ВесьСправочник"),
+  /**
+   * В пределах подчинения - уникальность кода проверяется в пределах подчинения
+   */
+  WITHIN_SUBORDINATION("WithinSubordination", "ВПределахПодчинения"),
+  /**
+   * В пределах подчинения владельцу - уникальность кода проверяется в пределах подчинения владельцу
+   */
+  WITHIN_OWNER_SUBORDINATION("WithinOwnerSubordination", "ВПределахПодчиненияВладельцу");
+
+  private static final Map<String, CodeSeries> KEYS = EnumWithName.computeKeys(values());
+
+  /**
+   * Полное имя элемента перечисления (на русском и английском языках)
+   */
+  @Getter
+  @Accessors(fluent = true)
+  private final MultiName fullName;
+
+  /**
+   * Constructs an enum constant with English and Russian full names.
+   *
+   * @param nameEn English full name for the enum constant
+   * @param nameRu Russian full name for the enum constant
+   */
+  CodeSeries(String nameEn, String nameRu) {
+    this.fullName = MultiName.create(nameEn, nameRu);
+  }
+
+  /**
+   * Finds a CodeSeries by its English or Russian name.
+   *
+   * Lookup is case-insensitive; if no match is found the WHOLE_CATALOG constant is returned.
+   *
+   * @param string the English or Russian name to look up
+   * @return the matching CodeSeries, or WHOLE_CATALOG if no match is found
+   */
+  public static CodeSeries valueByName(String string) {
+    return KEYS.getOrDefault(string.toLowerCase(Locale.ROOT), WHOLE_CATALOG);
+  }
+}

src/main/java/com/github/_1c_syntax/bsl/reader/common/xstream/ExtendXStream.java

@@ -1,3 +1,3 @@
 /*
  * This file is a part of MDClasses.
  *
@@ -21,6 +21,14 @@
  */
 package com.github._1c_syntax.bsl.reader.common.xstream;
 
+import java.io.File;
+import java.lang.reflect.InvocationTargetException;
+import java.nio.file.Path;
+import java.util.Objects;
+import java.util.function.Function;
+
+import javax.annotation.Nullable;
+
 import com.github._1c_syntax.bsl.mdclasses.ConfigurationTree;
 import com.github._1c_syntax.bsl.mdclasses.ExternalDataProcessor;
 import com.github._1c_syntax.bsl.mdclasses.ExternalReport;
@@ -31,6 +39,7 @@
 import com.github._1c_syntax.bsl.mdo.storage.form.FormElementType;
 import com.github._1c_syntax.bsl.mdo.support.ApplicationRunMode;
 import com.github._1c_syntax.bsl.mdo.support.AutoRecordType;
+import com.github._1c_syntax.bsl.mdo.support.CodeSeries;
 import com.github._1c_syntax.bsl.mdo.support.ConfigurationExtensionPurpose;
 import com.github._1c_syntax.bsl.mdo.support.DataLockControlMode;
 import com.github._1c_syntax.bsl.mdo.support.DataSeparation;
@@ -79,19 +88,13 @@
 import com.thoughtworks.xstream.mapper.Mapper;
 import com.thoughtworks.xstream.mapper.SecurityMapper;
 import com.thoughtworks.xstream.security.WildcardTypePermission;
+
 import io.github.classgraph.ClassGraph;
 import io.github.classgraph.ClassInfo;
 import io.github.classgraph.HasName;
 import lombok.Getter;
 import lombok.extern.slf4j.Slf4j;
 
-import javax.annotation.Nullable;
-import java.io.File;
-import java.lang.reflect.InvocationTargetException;
-import java.nio.file.Path;
-import java.util.Objects;
-import java.util.function.Function;
-
 /**
  * Расширение функциональности XStream
  */
@@ -231,8 +234,13 @@
   }
 
   /**
-   * Переопределение списка регистрируемых конвертеров. Оставлены только те, что нужны, особенно исключены те,
-   * что вызывают недовольство у JVM, в связи с неправильным доступом при рефлексии
+   * Configure the converter set to a curated list required by ExtendXStream.
+   *
+   * Registers only the converters needed for the application's deserialization needs,
+   * including primitive, collection, map, array, reflection, and domain-specific enum
+   * converters, and scans the common-converter package for additional converters.
+   * Intentionally omits default converters that are known to cause JVM access or
+   * reflection issues.
    */
   @Override
   protected void setupConverters() {
@@ -273,8 +281,16 @@
     registerConverter(new EnumConverter<>(FormElementType.class));
     registerConverter(new EnumConverter<>(InterfaceCompatibilityMode.class));
     registerConverter(new EnumConverter<>(DateFractions.class));
+    registerConverter(new EnumConverter<>(CodeSeries.class));
   }
 
+  /**
+   * Configure XStream security, reference handling, and class alias registration.
+   *
+   * Sets the XStream mode to disable object reference tracking, grants wildcard
+   * type permission for the internal package "com.github._1c_syntax.**", and
+   * registers MD-related classes and aliases used during deserialization.
+   */
   private void init() {
     // настройки безопасности доступа к данным
     setMode(XStream.NO_REFERENCES);
@@ -356,4 +372,4 @@
     mapper = new CachingMapper(mapper);
     return mapper;
   }
-}
+}