Merge pull request #109 from autumn-library/feature/api-docs

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

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

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

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

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

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,25 @@
+// Помечает указанный класс как фабрику компонентов - дуб, из которого появляются желуди.
+// `&Дуб` сам по себе тоже является желудем, то есть может запрашивать прилепление частиц,
+// является объектом для обработки `&Напильник`ом, может иметь `&Спецификация` и так далее.
+//
+// Дуб обычно содержит методы, помеченные аннотацией `&Завязь`, которые возвращают желуди, но
+// может содержать и другие методы, не связанные непосредственно с созданием желудей.
+//
+// Размещается над конструктором класса.
+//
+// Параметры:
+//   Значение - Строка - Имя желудя. По умолчанию будет использовано имя типа объекта,
+//                       как оно возвращается функцией `ТипЗнч`.
+// Пример:
+// &Дуб
+// Процедура ПриСозданииОбъекта()
+// КонецПроцедуры
+// .
+// &Завязь
+// Функция ПользовательскийЖелудь() Экспорт
+// .   Возврат Новый ПользовательскийЖелудь();
+// КонецФункции
+//
 &Аннотация("Дуб")
 Процедура ПриСозданииОбъекта(Значение = "")
 

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

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

src/internal/Классы/АннотацияЗавязь.os

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

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

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

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

@@ -3,6 +3,15 @@
 
 Перем _ПрименяетсяТолькоНа;
 
+// Проверить, может ли текущий напильник применяться на указанном желуде.
+//
+// Параметры:
+//   ОпределениеЖелудя - ОпределениеЖелудя - Определение желудя, для которого проверяется
+//                                           применимость текущего напильника.
+//
+//  Возвращаемое значение:
+//   Булево - Истина, если напильник может применяться на указанном желуде, иначе Ложь.
+//
 Функция МожетПрименятьсяНа(ОпределениеЖелудя) Экспорт
 
 	НапильникМожетПрименяться = Ложь;
@@ -24,6 +33,31 @@
 
 КонецФункции
 
+// Специальный тип желудя для дополнительной обработки других желудей в процессе их создания.
+//
+// Может использоваться для добавления дополнительных действий или свойств создаваемым желудям. Метод `ОбработатьЖелудь`
+// **может** возвращать другой объект, который подменит текущий желудь, или обертку-декоратор над текущим желудем.
+//
+// Каждый `&Напильник` дополнительно имеет `&Прозвище("Напильник")`.
+//
+// Напильник сам по себе является желудем, однако в силу своей специфики он может запрашивать прилепление только
+// &Деталек и Поделки.
+//
+// Желудь, помеченный аннотацией `&Напильник`, должен реализовать следующий интерфейс:
+// * `Функция ОбработатьЖелудь(Желудь, ОпределениеЖелудя) Экспорт`
+//
+// Размещается над конструктором класса.
+//
+// Параметры:
+//   Значение - Строка - Имя желудя, под которым напильник добавляется в контекст Поделки.
+//   ПрименяетсяТолькоНа - Строка - Повторяемый параметр. Ограничивает применение напильника только на желудях
+//                                  с указанными именами.
+//
+// Пример:
+// &Напильник
+// Процедура ПриСозданииОбъекта()
+// КонецПроцедуры
+//
 &Аннотация("Напильник")
 &Прозвище("Напильник")
 Процедура ПриСозданииОбъекта(Значение = "", &Повторяемый ПрименяетсяТолькоНа = Неопределено)

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

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

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

@@ -1,3 +1,42 @@
+// Маркерная аннотация для указания, что прилепляемая частица
+// является желудем. Основной способ связывания желудей между собой.
+//
+// Может быть использована над параметром конструктора/метода завязи желудя, полем класса
+// или методом установки значения.
+//
+// Параметры:
+//   Значение - Строка - Имя прилепляемого желудя. Если не заполнено, используется имя параметра конструктора/поля
+//                       класса или часть имени метода для установки значения.
+//   Тип - Строка - Тип прилепляемого желудя. В случае передачи значения "Желудь", будет внедрен желудь как таковой.
+//                  Так же может быть указан тип-коллекция: "Массив", "ТаблицаЗначений" и другие. Полный список
+//                  доступных типов см. в библиотеке
+//                  [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)
 	_Значение = Значение;
-КонецПроцедуры
+КонецПроцедуры