Докуметация по API #109
Докуметация по API #109
Conversation
WalkthroughВ данном пулл-запросе добавлены новые маркерные аннотации в файлы Changes
Possibly related PRs
Poem
📜 Recent review detailsConfiguration used: CodeRabbit UI 📒 Files selected for processing (7)
🚧 Files skipped from review as they are similar to previous changes (7)
Thank you for using CodeRabbit. We offer it for free to the OSS community and would appreciate your support in helping us grow. If you find it useful, would you consider giving us a shout-out on your favorite social media? 🪧 TipsChatThere are 3 ways to chat with CodeRabbit:
Note: Be mindful of the bot's finite context window. It's strongly recommended to break down tasks such as reading entire modules into smaller chunks. For a focused discussion, use review comments to chat about specific files and their changes, instead of using the PR comments. CodeRabbit Commands (Invoked using PR comments)
Other keywords and placeholders
CodeRabbit Configuration File (
|
Pull Request Test Coverage Report for Build 11919938340Details
💛 - Coveralls |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (2)
src/internal/Классы/АннотацияДеталька.os (1)
1-12: Предлагаю дополнить документацию примерами использованияДокументация хорошо структурирована, но было бы полезно добавить:
- Пример использования аннотации с параметрами
- Пример использования без параметров (с значениями по умолчанию)
- Более подробное описание поведения при использовании
ЗначениеПоУмолчаниюПример дополнения:
// ЗначениеПоУмолчанию - Произвольный - Значение, которое принимает деталька, если не задано из-вне. +// +// Пример: +// &Деталька("app.database.connection") +// Процедура УстановитьСтрокуПодключения(Знач СтрокаПодключения) Экспорт +// ... +// КонецПроцедуры +// +// &Деталька(ЗначениеПоУмолчанию = 5000) +// Перем ТаймаутПодключения Экспорт;src/internal/Классы/АннотацияПластилин.os (1)
1-13: Документация хорошо структурирована, но есть возможности для улучшенияПредлагаю добавить:
- Пример использования аннотации
- Ссылку на документацию по всем доступным значениям параметра
ТипПредлагаю добавить после строки 13:
// Пример: // &Пластилин(Значение = "МойЖелудь", Тип = "Массив") // Процедура УстановитьЗначения(Знач Параметр) Экспорт // КонецПроцедуры
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (3)
src/internal/Классы/АннотацияБлестяшка.os(1 hunks)src/internal/Классы/АннотацияДеталька.os(1 hunks)src/internal/Классы/АннотацияПластилин.os(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- src/internal/Классы/АннотацияБлестяшка.os
🔇 Additional comments (1)
src/internal/Классы/АннотацияПластилин.os (1)
14-15: Корректная реализация конструктора
Параметры конструктора соответствуют документации, значения по умолчанию заданы корректно.
This comment has been minimized.
This comment has been minimized.
nixel2007
force-pushed
the
feature/api-docs
branch
from
69995cc
to
3364d4e
Compare
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (4)
src/internal/Классы/АннотацияБлестяшка.os (1)
Line range hint
15-19: Корректная реализация маркерной аннотацииРеализация соответствует паттерну маркерной аннотации:
- Правильно указан атрибут аннотации
- Пустая процедура ПриСозданииОбъекта является ожидаемой для маркерной аннотации
Для улучшения читаемости кода предлагаю добавить экспорт к процедуре:
&Аннотация("Блестяшка") -Процедура ПриСозданииОбъекта() +Процедура ПриСозданииОбъекта() Экспорт🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияБлестяшка.os#L1
Программные модули не должны иметь закомментированных фрагментов кодаsrc/internal/Классы/АннотацияДеталька.os (1)
1-35: Предложения по улучшению документацииДокументация хорошо структурирована, но рекомендуется добавить:
- Более подробное описание интеграции с библиотекой configor
- Пример использования значения по умолчанию и как оно применяется в runtime
// Параметры: // Значение - Строка - Ключ настройки. См. библиотеку [configor](https://github.com/oscript-library/configor) // для полного описания синтаксиса. +// Пример: "Database.ConnectionString" или "App.Settings.Timeout" // Если не заполнено, используется имя параметра конструктора/поля класса // или часть имени метода для установки значения. // ЗначениеПоУмолчанию - Произвольный - Значение, которое принимает деталька, если не задано из-вне. +// Применяется только если значение не найдено в конфигурации.🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияДеталька.os#L1
Программные модули не должны иметь закомментированных фрагментов кодаsrc/internal/Классы/АннотацияПластилин.os (2)
1-37: Отличная документация, но стоит добавить информацию о валидации параметровДокументация хорошо структурирована и содержит понятные примеры использования. Однако было бы полезно добавить информацию о том, какие значения параметров считаются допустимыми и как обрабатываются некорректные значения.
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияПластилин.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
38-41: Реализация корректна, но можно улучшить согласованностьПроцедура реализована правильно с использованием аннотации и параметров по умолчанию. Для улучшения согласованности с другими аннотациями в проекте, предлагаю добавить комментарий о назначении пустой реализации.
Предлагаемое изменение:
&Аннотация("Пластилин") Процедура ПриСозданииОбъекта(Значение = "", Тип = "", &Повторяемый Блестяшка = Неопределено) - + // Реализация не требуется для маркерной аннотации КонецПроцедуры
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (4)
src/internal/Классы/АннотацияБлестяшка.os(1 hunks)src/internal/Классы/АннотацияВерховный.os(1 hunks)src/internal/Классы/АннотацияДеталька.os(1 hunks)src/internal/Классы/АннотацияПластилин.os(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- src/internal/Классы/АннотацияВерховный.os
🧰 Additional context used
🪛 GitHub Check: autumn Sonarqube Results
src/internal/Классы/АннотацияБлестяшка.os
[warning] 1-1: src/internal/Классы/АннотацияБлестяшка.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
src/internal/Классы/АннотацияДеталька.os
[warning] 1-1: src/internal/Классы/АннотацияДеталька.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
src/internal/Классы/АннотацияПластилин.os
[warning] 1-1: src/internal/Классы/АннотацияПластилин.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
🔇 Additional comments (2)
src/internal/Классы/АннотацияБлестяшка.os (1)
1-14: Отличная документация с понятными примерами использования
Документация хорошо структурирована и содержит:
- Четкое описание назначения аннотации
- Ограничения по использованию
- Практические примеры применения
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияБлестяшка.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
src/internal/Классы/АннотацияДеталька.os (1)
Line range hint 36-39: Реализация корректна
Процедура ПриСозданииОбъекта реализована правильно с соответствующими параметрами по умолчанию, что полностью соответствует документации и требованиям аннотации.
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияДеталька.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Actionable comments posted: 2
🧹 Outside diff range and nitpick comments (1)
src/internal/Классы/АннотацияФинальныйШтрих.os (1)
1-9: Предложение: добавить пример использования аннотацииДокументация хорошо описывает назначение и правила использования аннотации. Для улучшения понимания предлагаю добавить пример кода, демонстрирующий применение аннотации в реальном классе.
Предлагаемое дополнение:
// Процедура должна быть помечена `Экспорт`ная. // +// Пример: +// +// &Аннотация("ФинальныйШтрих") +// Процедура ИнициализироватьСостояние() Экспорт +// ОбновитьКэш(); +// ПроверитьПодключение(); +// КонецПроцедуры
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (5)
src/internal/Классы/АннотацияВерховный.os(1 hunks)src/internal/Классы/АннотацияЖелудь.os(1 hunks)src/internal/Классы/АннотацияПорядок.os(1 hunks)src/internal/Классы/АннотацияФинальныйШтрих.os(1 hunks)src/internal/Классы/АннотацияХарактер.os(1 hunks)
✅ Files skipped from review due to trivial changes (1)
- src/internal/Классы/АннотацияЖелудь.os
🚧 Files skipped from review as they are similar to previous changes (1)
- src/internal/Классы/АннотацияВерховный.os
🔇 Additional comments (3)
src/internal/Классы/АннотацияХарактер.os (2)
1-19: Отличная документация!
Документация хорошо структурирована и содержит всю необходимую информацию:
- Четкое описание назначения аннотации
- Подробное объяснение двух типов характера
- Правильное форматирование параметров
- Наличие примеров использования
Line range hint 20-24: Проверьте необходимость реализации логики в процедуре
Процедура ПриСозданииОбъекта не содержит реализации. Если это намеренно, рекомендуется добавить комментарий, объясняющий причину пустой реализации.
Предлагаю добавить комментарий:
&Аннотация("Характер")
Процедура ПриСозданииОбъекта(Значение)
+ // Реализация будет добавлена в модуле управления жизненным циклом
КонецПроцедурыsrc/internal/Классы/АннотацияПорядок.os (1)
3-7: Документация функции оформлена корректно!
Описание возвращаемого значения четкое и понятное.
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (6)
src/internal/Классы/АннотацияПриемка.os (1)
1-11: Отличная документация, есть небольшое предложение по улучшениюДокументация хорошо структурирована и содержит всю необходимую информацию. Однако можно добавить пример использования аннотации для лучшего понимания.
Предлагаю добавить пример использования после описания параметров:
// Параметры: // Значение - Строка - Имя желудя, под которым приемка добавляется в контекст Поделки. // +// Пример: +// ```oscript +// &Приемка +// Процедура ПриДобавленииОпределенияЖелудя(ОпределениеЖелудя) Экспорт +// // Реализация проверки +// КонецПроцедуры +// ``` +//src/internal/Классы/АннотацияСпецификация.os (3)
3-7: Предлагаю расширить документацию методаРекомендуется добавить описание назначения метода и возможных значений.
// Сохраненное значение спецификации. +// +// Возвращает текущее значение спецификации жизненного цикла. +// Возможные значения соответствуют значениям СостоянияПриложения. // // Возвращаемое значение: // Строка
12-29: Рекомендуется пояснить маркер @unstableДокументация подробная и информативная, но следует объяснить значение маркера @unstable для пользователей API.
// `@unstable` +// Данный API может измениться в будущих версиях без предварительного уведомления // // Аннотация для указания жизненого цикла приложения...
31-33: Улучшить сообщение об ошибкеТекущая реализация корректна, но сообщение об ошибке можно сделать более информативным, добавив список допустимых значений.
Если СостоянияПриложения.Значения().Найти(_Значение) = Неопределено Тогда + ДопустимыеЗначения = СтрСоединить(СостоянияПриложения.Значения(), ", "); ТекстСообщения = СтрШаблон( - "Неверное значение спецификации %1", - _Значение + "Неверное значение спецификации '%1'. Допустимые значения: %2", + _Значение, + ДопустимыеЗначения );src/internal/Классы/ПрилепляторЧастиц.os (2)
92-92: Улучшение сообщения об ошибкеИзменение формулировки сообщения об ошибке улучшает его понятность. Однако рекомендуется добавить больше контекста в сообщение для упрощения отладки.
Предлагаю дополнить сообщение об ошибке:
- ВызватьИсключение "Неизвестный тип прилепляемого через &Пластилин значения"; + ВызватьИсключение СтрШаблон( + "Неизвестный тип прилепляемого через &Пластилин значения: %1. Поддерживаемые типы: Желудь, %2", + ТипЖелудя, + СтрСоединить(УправляющийПрилепляемымиКоллекциями.ПолучитьТипыПрилепляемыхКоллекций(), ", ") + );
Line range hint
1-124: Унификация обработки ошибокВ коде используются разные подходы к формированию сообщений об ошибках:
- Прямые строки:
ВызватьИсключение "Неизвестный тип..."- СтрШаблон:
ВызватьИсключение СтрШаблон("Неизвестный тип прилепляемой частицы в свойстве/методе %1", ИмяСвойства)- Конкатенация:
ВызватьИсключение "Неизвестная аннотация " + Аннотация.Имя()Рекомендуется унифицировать подход к формированию сообщений об ошибках, используя
СтрШаблонво всех случаях для улучшения поддерживаемости кода. Например:- ВызватьИсключение "Неизвестная аннотация " + Аннотация.Имя(); + ВызватьИсключение СтрШаблон("Неизвестная аннотация: %1", Аннотация.Имя());
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (9)
src/internal/Классы/АннотацияПластилин.os(1 hunks)src/internal/Классы/АннотацияПорядок.os(1 hunks)src/internal/Классы/АннотацияПриемка.os(1 hunks)src/internal/Классы/АннотацияСпецификация.os(1 hunks)src/internal/Классы/АннотацияТабакерка.os(1 hunks)src/internal/Классы/АннотацияФинальныйШтрих.os(1 hunks)src/internal/Классы/АннотацияХарактер.os(1 hunks)src/internal/Классы/ПрилепляторЧастиц.os(1 hunks)src/Модули/СостоянияПриложения.os(1 hunks)
✅ Files skipped from review due to trivial changes (2)
- src/internal/Классы/АннотацияТабакерка.os
- src/Модули/СостоянияПриложения.os
🚧 Files skipped from review as they are similar to previous changes (4)
- src/internal/Классы/АннотацияПластилин.os
- src/internal/Классы/АннотацияПорядок.os
- src/internal/Классы/АннотацияФинальныйШтрих.os
- src/internal/Классы/АннотацияХарактер.os
🔇 Additional comments (2)
src/internal/Классы/АннотацияПриемка.os (2)
Line range hint 12-17: Корректная структура аннотаций
Все необходимые аннотации присутствуют и соответствуют документации. Порядок их объявления логичен.
Line range hint 17-19: Проверьте реализацию интерфейса
Класс требует реализации метода ПриДобавленииОпределенияЖелудя, как указано в документации. Убедитесь, что все классы, использующие эту аннотацию, реализуют требуемый метод.
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (3)
src/internal/Классы/АннотацияПриемка.os (1)
1-23: Документация хорошо структурирована, но пример можно улучшитьДокументация подробно описывает назначение и использование аннотации. Однако, пример использования можно сделать более информативным, добавив контекст создания и регистрации желудя.
Предлагаю расширить пример:
Пример: + + // КлассПроверкиЖелудей.os + &Приемка("ПроверкаЖелудей") + Процедура ПриСозданииОбъекта() + КонецПроцедуры Процедура ПриДобавленииОпределенияЖелудя(ОпределениеЖелудя) Экспорт Сообщить("Определение желудя: " + ОпределениеЖелудя.Имя()); + + // Дополнительная валидация желудя + Если ОпределениеЖелудя.Имя() = "" Тогда + ВызватьИсключение "Имя желудя не может быть пустым"; + КонецЕсли; КонецПроцедуры - . - &Приемка - Процедура ПриСозданииОбъекта() - КонецПроцедуры🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияПриемка.os#L1
Программные модули не должны иметь закомментированных фрагментов кодаsrc/internal/Классы/АннотацияРогатка.os (2)
4-20: Функции реализованы корректно, но документацию можно улучшитьПредлагаю дополнить документацию примерами использования функций для большей ясности.
Пример улучшения документации для функции ЗапускатьВФоне:
// Флаг необходимости запуска рогатки в фоновом задании. // // Возвращаемое значение: // Булево // +// Пример: +// Если РогаткаОбъект.ЗапускатьВФоне() Тогда +// // Логика для фонового выполнения +// КонецЕсли
22-42: Добавить проверку реализации интерфейсаДокументация хорошо описывает требования к классу с аннотацией
&Рогатка, но было бы полезно добавить проверку наличия методаПриЗапускеПриложенияво время выполнения.Хотите, чтобы я предложил реализацию проверки наличия обязательного метода?
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 22-22: src/internal/Классы/АннотацияРогатка.os#L22
Программные модули не должны иметь закомментированных фрагментов кода
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (3)
src/internal/Классы/АннотацияПриемка.os(1 hunks)src/internal/Классы/АннотацияРогатка.os(1 hunks)src/internal/Классы/АннотацияФинальныйШтрих.os(1 hunks)
🧰 Additional context used
📓 Learnings (1)
src/internal/Классы/АннотацияФинальныйШтрих.os (1)
Learnt from: nixel2007
PR: autumn-library/autumn#109
File: src/internal/Классы/АннотацияФинальныйШтрих.os:10-13
Timestamp: 2024-11-14T18:36:04.275Z
Learning: При объявлении аннотации, процедура `ПриСозданииОбъекта` не должна быть помечена как `Экспорт`. Это требуется только при использовании аннотации, а не при её объявлении.
🪛 GitHub Check: autumn Sonarqube Results
src/internal/Классы/АннотацияПриемка.os
[warning] 1-1: src/internal/Классы/АннотацияПриемка.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
src/internal/Классы/АннотацияРогатка.os
[warning] 22-22: src/internal/Классы/АннотацияРогатка.os#L22
Программные модули не должны иметь закомментированных фрагментов кода
src/internal/Классы/АннотацияФинальныйШтрих.os
[warning] 1-1: src/internal/Классы/АннотацияФинальныйШтрих.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
🔇 Additional comments (4)
src/internal/Классы/АннотацияФинальныйШтрих.os (2)
1-16: Документация корректна и полезна!
Предупреждение статического анализатора о закомментированном коде можно игнорировать, так как эти комментарии являются документацией с примерами использования, а не мертвым кодом.
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияФинальныйШтрих.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
21-24: Корректное объявление аннотации!
Процедура ПриСозданииОбъекта правильно объявлена без ключевого слова Экспорт, так как это объявление аннотации, а не её использование.
src/internal/Классы/АннотацияПриемка.os (1)
Line range hint 24-28: Корректная реализация аннотации
Реализация содержит все необходимые аннотации и корректно определяет процедуру с опциональным параметром.
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияПриемка.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
src/internal/Классы/АннотацияРогатка.os (1)
Line range hint 43-49: Проверить значения по умолчанию для параметров
Текущая реализация устанавливает ЗапускатьВФоне = Истина и ОжидатьЗавершения = Истина по умолчанию. Это может привести к неожиданному поведению, если разработчик явно не указал эти параметры.
✅ Verification successful
Let's examine the actual usage patterns of these parameters by looking at the test implementations.
Let's check the test files with the correct path to understand the usage patterns better.
Значения по умолчанию для параметров рогатки корректны
На основе анализа кодовой базы можно сделать следующие выводы:
- В тестах явно указывается
ЗапускатьВФоне = Ложьдля синхронных рогаток, что подтверждает правильность значения по умолчаниюИстина - Параметр
ОжидатьЗавершения = Истинапо умолчанию также оправдан, так как:- Обеспечивает корректную обработку ошибок (видно в
ПадениеРогаткиДолжноБытьЗалогировано.os) - Позволяет контролировать порядок выполнения рогаток
- Обеспечивает корректную обработку ошибок (видно в
- В
ЗапускательПриложения.osреализована полная поддержка всех комбинаций параметров
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Поиск использования класса АннотацияРогатка для анализа типичных параметров
# Поиск использования аннотации
rg -l "Рогатка" | grep -v "АннотацияРогатка.os"
Length of output: 737
Script:
#!/bin/bash
# Search for actual usage patterns in test files
rg -A 5 "Рогатка" "tests/ТестКлассы/Классы/*.os"
Length of output: 169
Script:
#!/bin/bash
# Check implementation details in ПриемкаРогатка
cat "src/internal/Классы/ПриемкаРогатка.os"
Length of output: 722
Script:
#!/bin/bash
# Look for usage in ЗапускательПриложения
cat "src/internal/Классы/ЗапускательПриложения.os"
Length of output: 2606
Script:
#!/bin/bash
# Search for actual usage patterns in test files with correct path
rg -A 5 "Рогатка" "tests/ТестКлассы/Классы"
# Also check the test that verifies error handling
cat "tests/ИзолированныеТесты/ПадениеРогаткиДолжноБытьЗалогировано.os"
Length of output: 3009
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 22-22: src/internal/Классы/АннотацияРогатка.os#L22
Программные модули не должны иметь закомментированных фрагментов кода
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (1)
src/internal/Классы/АннотацияОсобоеОбращение.os (1)
Line range hint
31-67: Улучшить сообщения об ошибкахРеализация включает хорошую валидацию параметров, но сообщения об ошибках можно сделать более информативными.
Предлагаю следующие улучшения:
- ВызватьИсключение "Нельзя одновременно отключать все напильники и задавать ограничения ""только"""; + ВызватьИсключение СтрШаблон("Нельзя одновременно отключать все напильники и задавать ограничения ""только"". Заданы напильники: %1", СтрСоединить(ПрименятьТолькоНапильник, ", ")); - ВызватьИсключение "Нельзя одновременно отключать все напильники и задавать ограничения ""не"""; + ВызватьИсключение СтрШаблон("Нельзя одновременно отключать все напильники и задавать ограничения ""не"". Заданы напильники: %1", СтрСоединить(НеПрименятьНапильник, ", ")); - ВызватьИсключение "Нельзя одновременно задавать ограничения ""только"" и ""не"""; + ВызватьИсключение СтрШаблон("Нельзя одновременно задавать ограничения ""только"" (%1) и ""не"" (%2)", + СтрСоединить(ПрименятьТолькоНапильник, ", "), + СтрСоединить(НеПрименятьНапильник, ", "));Это позволит разработчикам быстрее понять причину ошибки, показывая конкретные значения конфликтующих параметров.
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (3)
src/internal/Классы/АннотацияВерховный.os(1 hunks)src/internal/Классы/АннотацияОсобоеОбращение.os(1 hunks)src/internal/Классы/АннотацияПрозвище.os(1 hunks)
🧰 Additional context used
🪛 GitHub Check: autumn Sonarqube Results
src/internal/Классы/АннотацияВерховный.os
[warning] 1-1: src/internal/Классы/АннотацияВерховный.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
src/internal/Классы/АннотацияПрозвище.os
[warning] 1-1: src/internal/Классы/АннотацияПрозвище.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
🔇 Additional comments (6)
src/internal/Классы/АннотацияПрозвище.os (2)
1-15: Отличная документация!
Документация хорошо структурирована и содержит все необходимые элементы:
- Подробное описание назначения
- Четкое описание параметров
- Практический пример использования
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияПрозвище.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
16-19: Проверить реализацию пустой процедуры
Пустая реализация ПриСозданииОбъекта выглядит корректно для маркерной аннотации, но давайте проверим соответствие шаблону в других аннотациях.
✅ Verification successful
Пустая реализация процедуры соответствует шаблону
На основе анализа исходного кода других аннотаций в проекте, пустая реализация процедуры ПриСозданииОбъекта в аннотации Прозвище является корректной и соответствует общему шаблону. Многие другие маркерные аннотации (например, Блестяшка, Верховный, ФинальныйШтрих) также имеют пустую реализацию процедуры ПриСозданииОбъекта.
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Проверка реализации ПриСозданииОбъекта в других аннотациях
# Поиск всех реализаций ПриСозданииОбъекта в аннотациях
ast-grep --pattern $'&Аннотация($_)
Процедура ПриСозданииОбъекта($_) {
$$$
}'
Length of output: 80
Script:
#!/bin/bash
# Поиск файлов аннотаций и просмотр их содержимого
fd -e os "Аннотация.*\.os$" -x cat {}
Length of output: 17990
src/internal/Классы/АннотацияВерховный.os (2)
1-22: Отличная документация с подробными примерами!
Документация хорошо структурирована, содержит исчерпывающее описание назначения аннотации и наглядные примеры использования. Особенно ценно описание поведения в конфликтных ситуациях.
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияВерховный.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
23-25: Реализация соответствует шаблону аннотаций
Реализация процедуры ПриСозданииОбъекта следует общему шаблону аннотаций в проекте.
src/internal/Классы/АннотацияОсобоеОбращение.os (2)
21-30: Отличная документация!
Подробное описание назначения аннотации и параметров. Особенно ценно явное описание конфликтующих параметров, что поможет разработчикам избежать ошибок при использовании.
Line range hint 31-67: Проверить покрытие тестами
Убедитесь, что все новые проверки параметров покрыты модульными тестами, особенно:
- Проверка типов параметров
- Все комбинации конфликтующих параметров
- Граничные случаи (пустые коллекции, неопределено)
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (2)
src/internal/Классы/АннотацияДуб.os (1)
21-24: Рекомендуется добавить валидацию параметраПредлагаю добавить проверку значения параметра
Значениена допустимые символы, так как это имя будет использоваться в качестве идентификатора.Пример реализации:
&Аннотация("Дуб") Процедура ПриСозданииОбъекта(Значение = "") + Если ЗначениеЗаполнено(Значение) Тогда + ВызватьИсключение "Значение должно содержать только буквы, цифры и символ подчеркивания"; + КонецЕсли; КонецПроцедурыsrc/internal/Классы/АннотацияЗавязь.os (1)
1-17: Добавьте документацию по возвращаемому значению в примереДокументация хорошо структурирована и содержит подробное описание назначения, параметров и примера использования аннотации. Однако в примере кода было бы полезно добавить комментарий о типе возвращаемого значения функции
ПользовательскийЖелудь.Предлагаю дополнить пример:
// &Завязь // Функция ПользовательскийЖелудь(&Пластилин Зависимость, &Деталька ВажнаяНастройка) Экспорт +// Возвращаемое значение: +// ПользовательскийЖелудь - Созданный экземпляр желудя // . Возврат Новый ПользовательскийЖелудь(Зависимость, ВажнаяНастройка); // КонецФункции
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (8)
src/internal/Классы/АннотацияДуб.os(1 hunks)src/internal/Классы/АннотацияЖелудь.os(1 hunks)src/internal/Классы/АннотацияЗавязь.os(1 hunks)src/internal/Классы/АннотацияОсобоеОбращение.os(2 hunks)src/internal/Классы/АннотацияПриемка.os(1 hunks)src/internal/Классы/АннотацияПрозвище.os(1 hunks)src/internal/Классы/АннотацияРогатка.os(1 hunks)src/internal/Классы/АннотацияСпецификация.os(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (6)
- src/internal/Классы/АннотацияЖелудь.os
- src/internal/Классы/АннотацияОсобоеОбращение.os
- src/internal/Классы/АннотацияПриемка.os
- src/internal/Классы/АннотацияПрозвище.os
- src/internal/Классы/АннотацияРогатка.os
- src/internal/Классы/АннотацияСпецификация.os
🔇 Additional comments (2)
src/internal/Классы/АннотацияДуб.os (1)
1-20: Отличная документация!
Документация хорошо структурирована, содержит подробное описание назначения аннотации, параметров и пример использования. Особенно полезно объяснение взаимосвязи с другими аннотациями (&Завязь, &Напильник, &Спецификация).
src/internal/Классы/АннотацияЗавязь.os (1)
Line range hint 18-22: Проверьте использование аннотации в кодовой базе
Реализация процедуры ПриСозданииОбъекта корректна. Давайте проверим правильность использования аннотации в существующем коде.
✅ Verification successful
Let me analyze the results and generate a final response in Russian.
Использование аннотации &Завязь соответствует требованиям
Анализ показывает, что аннотация &Завязь используется корректно:
- В тестовых файлах она применяется для проверки различных сценариев использования
- В основном коде она используется над экспортными функциями и процедурами
- Документация в README.md подтверждает правильность использования
- Аннотация может использоваться как с параметрами (Тип, Значение), так и без них
- Она корректно взаимодействует с другими аннотациями (
&Пластилин,&Блестяшка,&Характер)
🏁 Scripts executed
The following scripts were executed for the analysis:
Script:
#!/bin/bash
# Description: Проверка использования аннотации &Завязь
# Expected: Аннотация должна использоваться только над экспортными функциями в классах с аннотацией &Дуб
# Поиск использования аннотации
rg -A 5 '&Завязь'
# Проверка контекста использования (должно быть внутри классов с &Дуб)
ast-grep --pattern $'&Дуб
$$$
&Завязь
Функция $_($$$) Экспорт
$$$'
Length of output: 13621
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (1)
src/internal/Классы/АннотацияНапильник.os (1)
36-55: Предложения по улучшению документацииДокументация подробная и информативная, но можно внести небольшие улучшения:
- Добавить пример использования аннотации
- Указать типы возвращаемого значения для метода
ОбработатьЖелудьПредлагаемое дополнение к документации:
// Желудь, помеченный аннотацией `&Напильник`, должен реализовать следующий интерфейс: -// * `Функция ОбработатьЖелудь(Желудь, ОпределениеЖелудя) Экспорт` +// * `Функция ОбработатьЖелудь(Желудь, ОпределениеЖелудя) Экспорт` - возвращает Произвольный +// +// Пример: +// ``` +// &Напильник("МойНапильник", "ЦелевойЖелудь") +// Процедура ПриСозданииОбъекта() +// // ... +// КонецПроцедуры +// ```
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (3)
src/internal/Классы/АннотацияНапильник.os(2 hunks)src/internal/Классы/АннотацияПриемка.os(1 hunks)src/internal/Классы/АннотацияРогатка.os(1 hunks)
🚧 Files skipped from review as they are similar to previous changes (2)
- src/internal/Классы/АннотацияПриемка.os
- src/internal/Классы/АннотацияРогатка.os
🧰 Additional context used
📓 Learnings (1)
src/internal/Классы/АннотацияНапильник.os (1)
Learnt from: nixel2007
PR: autumn-library/autumn#89
File: src/internal/Классы/АннотацияНапильник.os:6-27
Timestamp: 2024-11-12T14:20:38.625Z
Learning: Прозвища в функции `МожетПрименятьсяНа` теперь всегда включают имя жёлудя, что исключает необходимость явного добавления имени жёлудя в список идентификаторов для проверки.
🔇 Additional comments (1)
src/internal/Классы/АннотацияНапильник.os (1)
6-14: Корректная реализация функции МожетПрименятьсяНа
Реализация функции логически верна и соответствует требованиям. Документация функции хорошо структурирована.
Also applies to: 15-35
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
This comment has been minimized.
There was a problem hiding this comment.
Actionable comments posted: 0
🧹 Outside diff range and nitpick comments (2)
src/internal/Классы/АннотацияЗаготовка.os (1)
16-19: Рекомендуется расширить пример использованияТекущий пример демонстрирует только базовый синтаксис. Предлагаю дополнить его реальным примером реализации метода
ПриИнициализацииПоделки, чтобы показать типичный сценарий использования аннотации.Пример улучшенной документации:
// Пример: // &Заготовка // Процедура ПриСозданииОбъекта() // КонецПроцедуры +// +// Процедура ПриИнициализацииПоделки(Поделка) Экспорт +// // Добавление нового класса в систему типов +// ДобавитьКласс("МойКласс", "path/to/class.os"); +// // Или импорт библиотеки +// ДобавитьБиблиотеку("МояБиблиотека"); +// КонецПроцедурыsrc/internal/Классы/АннотацияНапильник.os (1)
Line range hint
6-34: Добавить проверку входного параметраФункция реализована корректно, но рекомендуется добавить проверку входного параметра на null и тип.
Предлагаю добавить следующую проверку в начало функции:
Функция МожетПрименятьсяНа(ОпределениеЖелудя) Экспорт + Ожидаем.Что(ОпределениеЖелудя, "Определение желудя не может быть неопределено").Заполнено(); + Ожидаем.Что(ОпределениеЖелудя, "Некорректный тип параметра").ИмеетТип("ОпределениеЖелудя"); НапильникМожетПрименяться = Ложь;
📜 Review details
Configuration used: CodeRabbit UI
Review profile: CHILL
📒 Files selected for processing (2)
src/internal/Классы/АннотацияЗаготовка.os(1 hunks)src/internal/Классы/АннотацияНапильник.os(2 hunks)
🧰 Additional context used
📓 Learnings (1)
src/internal/Классы/АннотацияНапильник.os (1)
Learnt from: nixel2007
PR: autumn-library/autumn#89
File: src/internal/Классы/АннотацияНапильник.os:6-27
Timestamp: 2024-11-12T14:20:38.625Z
Learning: Прозвища в функции `МожетПрименятьсяНа` теперь всегда включают имя жёлудя, что исключает необходимость явного добавления имени жёлудя в список идентификаторов для проверки.
🪛 GitHub Check: autumn Sonarqube Results
src/internal/Классы/АннотацияЗаготовка.os
[warning] 1-1: src/internal/Классы/АннотацияЗаготовка.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
src/internal/Классы/АннотацияНапильник.os
[warning] 36-36: src/internal/Классы/АннотацияНапильник.os#L36
Программные модули не должны иметь закомментированных фрагментов кода
🔇 Additional comments (2)
src/internal/Классы/АннотацияЗаготовка.os (1)
Line range hint 20-24: Корректная реализация аннотации
Реализация содержит все необходимые аннотации и правильную сигнатуру конструктора. Пустая реализация допустима для определения аннотации.
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 1-1: src/internal/Классы/АннотацияЗаготовка.os#L1
Программные модули не должны иметь закомментированных фрагментов кода
src/internal/Классы/АннотацияНапильник.os (1)
36-60: Отличная документация!
Документация подробно описывает назначение аннотации, требования к интерфейсу и содержит примеры использования. Всё оформлено согласно стандартам.
🧰 Tools
🪛 GitHub Check: autumn Sonarqube Results
[warning] 36-36: src/internal/Классы/АннотацияНапильник.os#L36
Программные модули не должны иметь закомментированных фрагментов кода
| @@ -1,3 +1,18 @@ | |||
| // Маркерная аннотация для указания, что прилепляемая частица | |||
| // является произвольным значением, передавамым кодом. | |||
There was a problem hiding this comment.
Передаваемым в конструктор жёлудя вероятно (да у завязи это формально метод а не конструктор, но метод завязи суть конструктор жёлудя)
| // В случае конфликта имен при получении желудей или их регистрации, будет использован желудь с аннотацией `&Верховный`. | ||
| // | ||
| // При наличии нескольких желудей с одним и тем же прозвищем позволяет определить, какой из них следует возвращать | ||
| // при поиске единственного желудя по его прозвищу. |
There was a problem hiding this comment.
При поиске одного/конкретного верялрно, а то слово "единственный" после слова "несколько" как то слух режет
src/internal/Классы/АннотацияДуб.os
Outdated
| // `&Дуб` сам по себе тоже является желудем, то есть может запрашивать прилепление частиц, | ||
| // является объектом для обработки `&Напильник`ом, может иметь `&Спецификация` и так далее. | ||
| // | ||
| // Дуб содержит методы, помеченные аннотацией `&Завязь`, которые возвращают желуди. |
There was a problem hiding this comment.
Это требование или рекомендация или опыт?)
Наверное если требование то стоит написать "должен" или типа того, если рекомендация то поидее "следует размещать", если это просто описание логики, то наверное что-то типа, "обычно содержит завязи, но так же может содержать что вам в голову прийдет" или типа того
| // Может иметь параметры, каждый из которых должен быть промаркирован как &Пластилин, &Деталька или &Блестяшка. | ||
| // В указанные параметры автоматически будут прилеплены соответствующие частицы при создании желудя. | ||
| // | ||
| // Размещается над экспортной функцией в классе, проаннотированном как `&Дуб`. |
| @@ -18,6 +26,19 @@ | |||
|
|
|||
| КонецФункции | |||
|
|
|||
| // Маркерная аннотация, показывающая, что желудь требует изменений в процессе своего создания. | |||
There was a problem hiding this comment.
Требует особой логики обработки напильников наверное, или как-то так, а то изменений в процессе создания наводит на мысль что жёлудь требует перемен изменений самого жёлудя
There was a problem hiding this comment.
я хотел оставить общее описание аннотации максимально generic, чтобы оставить возможность напихать туда параметров для других компонентов. Смысл аннотации в том, что желудь требует особого обращения к себе, а вот в чем именно заключается это особое обращение уже перечислено в параметрах аннотации. WDYT?
| @@ -1,3 +1,41 @@ | |||
| // Маркерная аннотация для указания, что прилепляемая частица | |||
There was a problem hiding this comment.
Мне кажется описание не внесло никакой ясности, стоит я думаю сразу ноэа входе описать что это маркер который загрузит в поле/параметр жёлудь зарегистрированный в системе типов осени, или что-то типа того вероятно
There was a problem hiding this comment.
Я тут использовал термин "прилепление частиц", который есть в документации, но которого нет в API в явном виде (исключая модуль с типами прилепляемых частиц и класса ПрилепляторЧастиц). Если уж расписывать, то расписывать и здесь, и в детальке, и в блестяшке. Либо описывать термин где-то отдельно, "ссылаясь" на него.
| // Значение - Строка - Имя прилепляемого желудя. Если не заполнено, используется имя параметра конструктора/поля | ||
| // класса или часть имени метода для установки значения. | ||
| // Тип - Строка - Тип прилепляемого желудя. В случае передачи значения "Желудь", будет внедрен желудь как таковой. | ||
| // Так же может быть указан тип "Массив", "ТаблицаЗначений" и другие. Полный список доступных типов |
There was a problem hiding this comment.
Так же может быть указан тип-коллекция
| Функция Значение() Экспорт | ||
| Возврат _Значение; | ||
| КонецФункции | ||
|
|
||
| // `@unstable` |
There was a problem hiding this comment.
Ну а вот так. Я не уверен ещё. А ты?
There was a problem hiding this comment.
Я даже не уверен, что она работает, если честно.
There was a problem hiding this comment.
Как и &Приемка - смысл работает, а вот над названием не уверен.
There was a problem hiding this comment.
Я скорее к тому что это какая-то новая сущность которой ни в каком конвеншене нет, и мне кажется просто так вешать какой-то тег без объяснений и надеяться что тебя поймут затея сомнительная.)
There was a problem hiding this comment.
Я такое вешал в entity, и указывал в доке, что это такое х)
| @@ -1,3 +1,32 @@ | |||
| // Пометка, что прилепляемая частица прилепляется не непосредственно, а через специальный объект | |||
| // типа `Табакерка`, который позволяет получить частицу программно. | |||
There was a problem hiding this comment.
Я бы ещё указал что отложенно, т.е передает управление временем создания жёлудя внутрь жёлудя
Analysis Details0 Issues
Coverage and Duplications
Project ID: autumn |
|
Я замержу, пока есть возможность мержа. Но пластилин ещё можно дообсудить |
No description provided.