Докуметация по API

src/internal/Классы/АннотацияБлестяшка.os

@@ -1,3 +1,18 @@
+// Маркерная аннотация для указания, что прилепляемая частица
+// является произвольным значением, передавамым кодом.
+//
+// Может быть использована только над параметром конструктора/метода завязи желудя.
+//
+// Пример:
+//
+// 1.
+// &Желудь
+// Процедура ПриСозданииОбъекта(&Блестяшка ПроизвольноеЗначение)
+//
+// 2.
+// &Завязь
+// Функция МойЖелудь(&Блестяшка ПроизвольноеЗначение) Экспорт
+//
 &Аннотация("Блестяшка")
 Процедура ПриСозданииОбъекта()
 

src/internal/Классы/АннотацияВерховный.os

@@ -1,3 +1,13 @@
+// Помечает желудь как имеющий приоритет среди других желудей с таким же именем или `&Прозвищем`.
+// В случае конфликта имен при получении желудей или их регистрации, будет использован желудь с аннотацией `&Верховный`.
+//
+// При наличии нескольких желудей с одним и тем же прозвищем позволяет определить, какой из них следует возвращать
+// при поиске единственного желудя по его прозвищу.
+//
+// Если несколько желудей с одним и тем же именем/прозвищем имеют аннотацию `&Верховный`, будет вызвано исключение.
+//
+// Размещается над определением желудя - конструктором или методом &Завязи.
+//
 &Аннотация("Верховный")
 Процедура ПриСозданииОбъекта()
 

src/internal/Классы/АннотацияДеталька.os

@@ -1,3 +1,38 @@
+// Маркерная аннотация для указания, что прилепляемая частица
+// является настройкой приложения.
+//
+// Может быть использована над параметром конструктора/метода завязи желудя, полем класса
+// или методом установки значения.
+//
+// Параметры:
+//   Значение - Строка - Ключ настройки. См. библиотеку [configor](https://github.com/oscript-library/configor)
+//                       для полного описания синтаксиса.
+//                       Если не заполнено, используется имя параметра конструктора/поля класса
+//                       или часть имени метода для установки значения.
+//   ЗначениеПоУмолчанию - Произвольный - Значение, которое принимает деталька, если не задано из-вне. 
+//
+// Пример:
+//
+//  1.
+//  &Деталька
+//  Перем ПутьКФайлу;
+//
+//  2.
+//  &Деталька(Значение = "Настройки.ПутьКФайлу", ЗначениеПоУмолчанию = "./file.txt")
+//  Перем ПутьКФайлу;
+//
+//  3.
+//  &Желудь
+//  Процедура ПриСозданииОбъекта(&Деталька ПутьКФайлу)
+//
+//  4.
+//  &Деталька
+//  Процедура УстановитьПутьКФайлу(Значение) Экспорт
+//
+//  5.
+//  &Завязь
+//  Функция МойЖелудь(&Деталька ПутьКФайлу) Экспорт
+//
 &Аннотация("Деталька")
 Процедура ПриСозданииОбъекта(Значение = "", ЗначениеПоУмолчанию = Неопределено)
 

src/internal/Классы/АннотацияЖелудь.os

@@ -1,3 +1,11 @@
+// Помечает указанный класс как желудь - компонент, жизненным циклом которого управляет фреймворк ОСень.
+//
+// Размещается над конструктором класса.
+//
+// Параметры:
+//   Значение - Строка- Имя желудя. По умолчанию будет использовано имя типа объекта,
+//                      как оно возвращается функцией `ТипЗнч`.
+//
 &Аннотация("Желудь")
 Процедура ПриСозданииОбъекта(Значение = "")
 

src/internal/Классы/АннотацияПластилин.os

@@ -1,3 +1,41 @@
+// Маркерная аннотация для указания, что прилепляемая частица
+// является желудем. Основной способ связывания желудей между собой.
+//
+// Может быть использована над параметром конструктора/метода завязи желудя, полем класса
+// или методом установки значения.
+//
+// Параметры:
+//   Значение - Строка - Имя прилепляемого желудя. Если не заполнено, используется имя параметра конструктора/поля
+//                       класса или часть имени метода для установки значения.
+//   Тип - Строка - Тип прилепляемого желудя. В случае передачи значения "Желудь", будет внедрен желудь как таковой.
+//                  Так же может быть указан тип "Массив", "ТаблицаЗначений" и другие. Полный список доступных типов
+//                  см. в библиотеке [autumn-collections](https://github.com/autumn-library/autumn-collections).
+//   Блестяшка - Произвольный - Повторяемый параметр. Передаваемые в прилепляемый желудь произвольные значения.
+//
+// Пример:
+//
+//  1.
+//  &Желудь
+//  Процедура ПриСозданииОбъекта(&Пластилин ДругойЖелудь)
+//
+//  2.
+//  &Желудь
+//  Процедура ПриСозданииОбъекта(
+//  .  &Пластилин(Значение = "ДругойЖелудь", Тип = "Массив", Блестяшка = "Парам1", Блестяшка = "Парам2") Зависимость
+//	)
+//
+//  3.
+//  &Пластилин
+//  Перем ДругойЖелудь;
+//
+//  4.
+//  &Завязь
+//  Функция МойЖелудь(&Пластилин ДругойЖелудь) Экспорт
+//
+//  5.
+//  &Пластилин
+//  Процедура УстановитьДругойЖелудь(Зависимость) Экспорт
+//
 &Аннотация("Пластилин")
 Процедура ПриСозданииОбъекта(Значение = "", Тип = "", &Повторяемый Блестяшка = Неопределено)
 

src/internal/Классы/АннотацияПорядок.os

@@ -1,10 +1,27 @@
 Перем _Значение;
 
+// Порядок, заданный аннотацией.
+//
+//  Возвращаемое значение:
+//   Число
+//
 Функция Значение() Экспорт
 	Возврат _Значение;
 КонецФункции
 
+// Управляет порядком инициализации и использования желудя. Не может быть меньше 1 или больше 999998.
+//
+// Если размещается над обычным `&Желудем` или `&Завязью`, то влияет на порядок сортировки, при получении 
+// коллекции желудей по прозвищу.
+//
+// Если размещается над `&Напильником`, влияет на порядок применения напильников к желудям.
+//
+// Если размещается над `&Рогаткой`, влияет на порядок запуска рогаток при старте приложения.
+//
+// Параметры:
+//   Значение - Число - Задаваемый порядок.
+//
 &Аннотация("Порядок")
 Процедура ПриСозданииОбъекта(Значение = 1)
 	_Значение = Значение;
-КонецПроцедуры
+КонецПроцедуры

src/internal/Классы/АннотацияПриемка.os

@@ -1,3 +1,27 @@
+// Специальный тип желудя для обработки определений желудей.
+//
+// Аналог &Напильника для `ОпределениеЖелудя`. Срабатывает каждый раз, когда в контекст добавляется новое
+// определение желудя. При добавлении самой Приемки в контекст, все ранее добавленные определения желудей
+// передаются в Приемку для проверки.
+//
+// Класс, помеченный аннотацией `&Приемка`, должен реализовать следующий интерфейс:
+// * `Процедура ПриДобавленииОпределенияЖелудя(ОпределениеЖелудя) Экспорт`
+//
+// Каждая `&Приемка` так же имеет `&Характер("Компанейский")`, `&Прозвище("Приемка")` и `&Спецификация("Инициализация")`
+//
+// Параметры:
+//   Значение - Строка - Имя желудя, под которым приемка добавляется в контекст Поделки.
+//
+// Пример:
+//
+// Процедура ПриДобавленииОпределенияЖелудя(ОпределениеЖелудя) Экспорт
+// .   Сообщить("Определение желудя: " + ОпределениеЖелудя.Имя());
+// КонецПроцедуры
+// .
+// &Приемка
+// Процедура ПриСозданииОбъекта()
+// КонецПроцедуры
+//
 &Аннотация("Приемка")
 &Прозвище("Приемка")
 &Характер("Компанейский")

src/internal/Классы/АннотацияРогатка.os

@@ -1,14 +1,46 @@
 Перем _ЗапускатьВФоне;
 Перем _ОжидатьЗавершения;
 
+// Флаг необходимости запуска рогатки в фоновом задании.
+//
+//  Возвращаемое значение:
+//   Булево
+//
 Функция ЗапускатьВФоне() Экспорт
 	Возврат _ЗапускатьВФоне;
 КонецФункции
 
+// Флаг необходимости ожидания завершения рогатки при ее запуске в фоновом задании.
+//
+//  Возвращаемое значение:
+//   Булево
+//
 Функция ОжидатьЗавершения() Экспорт
 	Возврат _ОжидатьЗавершения;
 КонецФункции
 
+// Специальный тип желудя, автоматически выполняемый при запуске приложения (`Поделка.ЗапуститьПриложение()`).
+//
+// Класс, помеченный аннотацией `&Рогатка`, должен реализовать следующий интерфейс:
+// * `Процедура ПриЗапускеПриложения() Экспорт`
+//
+// Каждая `&Рогатка` дополнительно имеет `&Прозвище("Рогатка")`.
+//
+// Параметры:
+//   Значение - Строка - Имя желудя, под которым рогатка добавляется в контекст Поделки.
+//   ЗапускатьВФоне - Булево - Если Истина, то рогатка будет запущена в фоновом задании.
+//                             Если Ложь, то рогатка будет запущена в текущем потоке.
+//   ОжидатьЗавершения - Булево - Если Истина и `ЗапускатьВФоне` = Истина,
+//                                то после запуска рогатки будет ожидаться её завершение.
+// Пример:
+// Процедура ПриЗапускеПриложения() Экспорт
+// .   Сообщить("Привет из рогатки!");
+// КонецПроцедуры
+// .
+// &Рогатка
+// Процедура ПриСозданииОбъекта()
+// КонецПроцедуры
+//
 &Аннотация("Рогатка")
 &Прозвище("Рогатка")
 Процедура ПриСозданииОбъекта(Значение = "", ЗапускатьВФоне = Истина, ОжидатьЗавершения = Истина)

src/internal/Классы/АннотацияСпецификация.os

@@ -1,17 +1,36 @@
 Перем _Значение;
 
+// Сохраненное значение спецификации.
+//
+//  Возвращаемое значение:
+//   Строка
+//
 Функция Значение() Экспорт
 	Возврат _Значение;
 КонецФункции
 
+// `@unstable`
+//
+// Аннотация для указания жизненого цикла приложения, начиная с которого разрешено создавать желудь.
+//
+// По умолчанию все желуди имеют спецификацию "Выполнение", означающую, что желудь может быть создан только после вызова
+// `Поделка.ЗапуститьПриложение()`.
+//
+// К желудям со специкацией "Инициализация" не применяются напильники.
+//
+// Параметры:
+//   Значение - Строка - Состояние приложения, на котором разрешено создавать желудь. См. СостоянияПриложения.
+//
+// Пример:
+// &Спецификация("Инициализация")
+// &Желудь
+// Процедура ПриСозданииОбъекта()
+// КонецПроцедуры
+//
 &Аннотация("Спецификация")
-Процедура ПриСозданииОбъекта(Значение)
+Процедура ПриСозданииОбъекта(Значение = "Выполнение")
 
-	Если Значение = Неопределено Тогда
-		_Значение = "Выполнение";
-	Иначе
-		_Значение = Значение;
-	КонецЕсли;
+	_Значение = Значение;
 
 	Если СостоянияПриложения.Значения().Найти(_Значение) = Неопределено Тогда
 		ТекстСообщения = СтрШаблон(

src/internal/Классы/АннотацияТабакерка.os

@@ -1,3 +1,32 @@
+// Пометка, что прилепляемая частица прилепляется не непосредственно, а через специальный объект
+// типа `Табакерка`, который позволяет получить частицу программно.
+//
+// Может использоваться для внедрения компанейских желудей, внедрения желудя самого в себя, 
+// для разрыва циклических зависимостей, для передачи дополнительных параметров прилепляемого желудя и т.п.
+//
+// Используется совместно с аннотациями `&Пластилин` и `&Деталька`.
+//
+// Пример:
+//
+// 1.
+// &Табакерка
+// &Пластилин("ДругойЖелудь")
+// Перем ТабакеркаСДругимЖелудем;
+// .
+// ДругойЖелудь = ТабакеркаСДругимЖелудем.Достать();
+// ДругойЖелудь.КакойТоМетод();
+// ...
+// 2.
+// &Табакерка
+// &Пластилин("ДругойЖелудь")
+// Перем ТабакеркаСДругимЖелудем;
+// .
+// МассивБлестяшек = Новый Массив;
+// МассивБлестяшек.Добавить("Парам1");
+// .
+// ДругойЖелудь = ТабакеркаСДругимЖелудем.Достать(МассивБлестяшек);
+// ДругойЖелудь.КакойТоМетод();
+//
 &Аннотация("Табакерка")
 Процедура ПриСозданииОбъекта()
 

src/internal/Классы/АннотацияФинальныйШтрих.os

@@ -1,3 +1,24 @@
+// Процедуры, помеченные аннотацией "ФинальныйШтрих" будут вызваны в конце инициализации желудя,
+// после отработки конструктора/метода завязи и всех напильников, применяемых на желуде.
+// Во время выполнения процедуры доступны все прилепляемые частицы, прилепленные как через конструктор,
+// так и через поля класса и методы-сеттеры.
+//
+// Желудь может содержать несколько процедур, помеченных аннотацией "ФинальныйШтрих".
+// Порядок их вызова не гарантируется.
+//
+// Процедура должна быть помечена `Экспорт`ная.
+//
+// Пример:
+// 
+// &ФинальныйШтрих
+// Процедура ПостИнициализация() Экспорт
+// .   Сообщить("Я выполнилась после конструктора объекта");
+// КонецПроцедуры
+// .
+// &Желудь
+// Процедура ПриСозданииОбъекта()
+// КонецПроцедуры
+//
 &Аннотация("ФинальныйШтрих")
 Процедура ПриСозданииОбъекта()
 

src/internal/Классы/АннотацияХарактер.os

@@ -1,3 +1,25 @@
+// Задает способ управления жизненным циклом желудя.
+//
+// ОСень содержит два базовых характера желудя: "Одиночка" и "Компанейский".
+//
+// По умолчанию все желуди имеют характер "Одиночка", означающий, что желудь
+// инициализируется один раз. При каждом запросе желудя будет возвращаться один и тот же
+// экземпляр.
+//
+// Характер "Компанейский" означает, что каждый раз при запросе желудя будет создаваться
+// новый экземпляр.
+//
+// Размещается над конструктором класса или над методом `&Завязи`.
+//
+// Параметры:
+//   Значение - Строка - Характер желудя.
+//
+// Пример:
+//  &Характер("Компанейский")
+//  &Желудь
+//  Процедура ПриСозданииОбъекта()
+//  КонецПроцедуры
+//
 &Аннотация("Характер")
 Процедура ПриСозданииОбъекта(Значение)