рутина: документирование кода

1 files changed, 149 insertions, 3 deletions

diff --git a/conf.typ b/conf.typ
index 4442e83..6d286b5 100644
--- a/conf.typ
+++ b/conf.typ
@@ -67,19 +67,73 @@
 
 
 #let modules = (
+	/*
+	 * Модуль информации об авторе
+	 * Позволяет получать более полную и отформатированную
+	 * информацию об авторе: студент/студентки/студентов (get_author_sex),
+	 * номер курса, группы и так далее.
+	 * Конечно, некоторые из этих вещей в открытом виде
+	 * лежат в словаре author, но некоторые данные
+	 * нуждаются в постобработке или вовсе получаются
+	 * косвенным путём. Необходимость в постобработке
+	 * может возникнуть и позднее, поэтому настоятельно
+	 * рекомендуется пользоваться именно этими методами, а 
+	 * не получать код напрямую.
+	 */
 	author_info: (
+		/*
+		 * Определяет студенческо-половую сущность автора.
+		 * Принимает:
+		 *  - author - словарь про автора
+		 * Возвращает:
+		 *  - В зависимости от пола: "студента", "студентки", "студентов"
+		 */
 		get_author_sex:
 			(author) => {
-				return strings.student.at(author.at("sex"), default: strings.error.no_sex)
+				return strings.student.at(
+					author.at("sex"),
+					default: strings.error.no_sex
+				)
 			},
+		/*
+		 * Определяет курс автора (по номеру группы)
+		 * Принимает:
+		 *  - author - словарь про автора
+		 * Возвращает:
+		 *  - Номер курса в строковом формате
+		 */
 		get_author_course:
 			(author) => {
 				return author.group.at(0)
 			},
+		/*
+		 * Определяет группу автора
+		 * Принимает:
+		 *  - author - словарь про автора
+		 * Возвращает:
+		 *  - Номер группы в строковом формате
+		 * Примечание: на текущий момент функция
+		 * ничего не делает, но, возможно, это
+		 * не навсегда и в будущем здесь что-то
+		 * может появиться. Чтобы потом не мучиться
+		 * с рефакторингом, лучше получать номер группы
+		 * через неё.
+		 */
 		get_author_group:
 			(author) => {
 				return author.group
 			},
+		/*
+		 * Определяет код и название направления автора
+		 * Принимает:
+		 *  - author - словарь про автора
+		 * Возвращает:
+		 *  - author.speciality, если таковой указан
+		 *  - В противном случае, если студент учится на КНиИТе,
+		 *    для студента работает аттракцион невиданной
+		 *    технологичности: код и название специальности
+		 *    определяются автоматически
+		 */
 		get_speciality:
 			(author) => {
 				if author.at("speciality", default: none) != none {
@@ -114,10 +168,27 @@
 				return strings.error.undefined_spec
 			}
 	),
+
+	/*
+	 * Модуль титульного листа
+	 * Здесь происходит генерация титульного листа и
+	 * определяются все необходимые для этого методы.
+	 * Поскольку его создание --- задача не такая уж
+	 * и тривиальная, здесь есть много приватных методов
+	 * и ваш покорный слуга ещё раз напоминает о
+	 * нежелательности их вызова извне. Если такая необходимость
+	 * всё же возникает, лучше переименовать метод и убрать
+	 * подчёркивание: впоследствии это можно будет хотя бы как-то
+	 * отладить.
+	 * 
+	 * Изначально задумывалось, что единственный доступный
+	 * для вызова извне метод --- make, а в остальных не 
+	 * должно возникнуть необходимости.
+	 */
 	title: (
 		/*
-		 * Отвечает за вывод названия университета
-		 * на титульном листе
+		 * Отвечает за вывод названия министерства и
+		 * университета на титульном листе
 		 */
 		_default_header:
 			() => {
@@ -128,6 +199,14 @@
 				text(weight: "bold", strings.title.sgu)
 				set align(left)
 			},
+		/*
+		 * Отвечает за вывод тела титульного листа:
+		 * заголовок (название работы, если не определено иное),
+		 * тип работы, информация об авторе
+		 * 
+		 * Информация о проверяющем преподавателе
+		 * генерируется не здесь по историческим причинам.
+		 */
 		_default_body:
 			(data) => {
 				set align(center)
@@ -180,6 +259,16 @@
 				let result = (self.utils.strglue)(sex, course, group)
 				return result
 			},
+		/*
+		 * Получает заголовок титульного листа.
+		 * Принимает:
+		 *  - info - информация о документе
+		 *  - type - тип документа
+		 * Возвращает:
+		 *  - В зависимости от типа:
+		 *    - Тему работы, если это не автореферат и не отчёт по НИРу
+		 *    - В противном случае названия соответствующих типов работ
+		 */
 		_get_title_string:
 			(info, type) => {
 				if type == "autoref" {
@@ -190,6 +279,20 @@
 				}
 				return info.at("title", default: [Тема работы])
 			},
+		/*
+		 * Генерирует строки текста для вывода на титульном листе
+		 * Принимает:
+		 *  - type - тип документа
+		 *  - info - информация о документе
+		 * Возвращает:
+		 *  - Словарь:
+		 *     title: Заголовок
+		 *     worktype: Тип работы
+		 *     group: студент(а|ки|ов) s курса sex группы
+		 *     specialty: направления 69.14.88 --- Специальность
+		 *     faculty: факультета XXX
+		 *     author: автор(ы)? работы
+		 */
 		_get_strings:
 			(self, type, info) => {
 				let author = info.at("author", default: (:))
@@ -210,6 +313,12 @@
 					author: author.name
 				)
 			},
+		/*
+		 * Генерирует титульный лист
+		 * Принимает:
+		 *  - type - тип документа
+		 *  - info - информация о документе
+		 */
 		make:
 			(self, type, info) => {
 				let strs = (self.title._get_strings)(self, type, info)
@@ -220,7 +329,21 @@
 				(self.title._default_footer)()
 			},
 	),
+
+	/*
+	 * Модуль генерации документа
+	 * Здесь содержатся методы, влияющие на вид всего
+	 * документа в целом. Главный из них --- make ---
+	 * вызывается из точки входа в стилевой файл и
+	 * отвечает за всё оформление выходного документа.
+	 */
 	document: (
+		/*
+		 * Генерирует весь документ
+		 * Принимает:
+		 *  - type - тип документа
+		 *  - info - информация о документе
+		 */
 		make:
 			(
 				self,
@@ -239,7 +362,27 @@
 				(self.title.make)(self, type, info)	
 			}
 	),
+
+	/*
+	 * Помощник
+	 * Модуль-помощник не содержит особой
+	 * функциональности и не имеет конкретного
+	 * назначения, но содержащиеся в нём методы
+	 * могут быть полезны где угодно и не 
+	 * привязаны к конкретной части документа
+	 */
 	utils: (
+		/*
+		 * Склеивает строки, игнорируя пустые
+		 * Принимает:
+		 *  - divider - разделитель (по умолчанию пробел)
+		 *  - соединяемые строки в неограниченном количестве
+		 * Примечание: метод похож по своей сути
+		 * на join, но отличается от него наличием проверки
+		 * на пустые строки: рядом с ними разделитель не
+		 * ставится, что исключает присутствие двух разделителей
+		 * подряд.
+		 */
 		strglue: 
 			(
 				divider: " ",
@@ -254,6 +397,9 @@
 					) {
 						result = result + " "
 					}
+					// TODO: string было бы неплохо обернуть
+					// в str(), но баг в системе типов Typst
+					// не позволяет этого сделать
 					result = result + string
 				}
 				return result