From 48c20aabb88bf911a8a1f99afec9839f498efb47 Mon Sep 17 00:00:00 2001
From: Evgeniya Bashieva <eugenia.bashieva@remago.com>
Date: Thu, 31 Jul 2025 18:38:05 +0200
Subject: [PATCH 1/2] feat: add lesson 12

---
 lessons/lesson12/lesson.md | 218 ++++++++++++++++++++++++++++++++++++-
 1 file changed, 217 insertions(+), 1 deletion(-)

diff --git a/lessons/lesson12/lesson.md b/lessons/lesson12/lesson.md
index 902f405..4c1f392 100644
--- a/lessons/lesson12/lesson.md
+++ b/lessons/lesson12/lesson.md
@@ -1 +1,217 @@
-# Lesson 12
+---
+title: Занятие 12
+description: "Работа с типами, JSDoc и TypeScript. Генерация документации и линтинг JS-файлов с типами"
+---
+
+# OTUS
+
+## Javascript / TypeScript
+
+<!--v-->
+
+## Зачем документировать код?
+
+- Не про комментарии, а про **описание интерфейсов** и API
+- Повышает читаемость и сопровождение
+- Улучшает работу команды и вхождение в проект
+- Используется IDE и автокомплитом
+
+<!--v-->
+
+## Что включает хорошая документация?
+
+- Назначение модуля/функции
+- Типы входных и выходных данных
+- Примеры использования
+- Указание особенностей или ограничений
+
+<!--v-->
+
+## Именование: основа читаемости
+
+- **Функции**: глаголы (`getUser`, `calculateTotal`)
+- **Модули**: предметная область (`authService`, `logger`)
+- **Переменные**:
+    - булевы: `isValid`, `hasPermission`
+    - коллекции: `users`, `items`
+    - константы: `MAX_LENGTH`, `DEFAULT_TIMEOUT`
+
+<!--v-->
+
+## Примеры наименований
+
+| Плохо     | Хорошо             |
+| --------- | ------------------ |
+| `data()`  | `fetchUserData()`  |
+| `check()` | `isAuthorized()`   |
+| `calc()`  | `calculatePrice()` |
+
+<!--s-->
+
+## Что такое JSDoc
+
+<!--v-->
+
+### Определение и цели
+
+- JSDoc — способ аннотировать JS-код для понимания структуры и типов
+- Не требует TypeScript!
+- Работает в любом `.js` файле
+
+<!--v-->
+
+### Пример JSDoc
+
+```js
+/**
+ * Складывает два числа
+ * @param {number} a Первое число
+ * @param {number} b Второе число
+ * @returns {number} Сумма
+ */
+function add(a, b) {
+  return a + b;
+}
+```
+
+<!--v-->
+
+### Основные теги JSDoc
+
+- `@param` — параметры функции
+- `@returns` — возвращаемое значение
+- `@example` — пример использования
+- `@typedef` — объявление типа
+- `@deprecated`, `@see`, `@throws` и др.
+
+<!--v-->
+
+### Как работает в редакторе
+
+- Подсказки и типы при наведении
+- Автокомплит параметров и возвращаемых значений
+- Можно использовать без TS!
+
+<!--s-->
+
+## TypeScript и JSDoc
+
+<!--v-->
+
+### Чем TypeScript лучше JSDoc
+
+|             | JSDoc               | TypeScript           |
+| ----------- | ------------------- | -------------------- |
+| Простота    | ✅                  | ❌ требует настройку |
+| Проверка    | ограничена          | ✅ строгая проверка  |
+| IDE-помощь  | 👍                  | 🔥 лучшее качество   |
+| Рефакторинг | ❌ (часто ломается) | ✅ надёжный          |
+
+<!--v-->
+
+### Пример JSDoc и TS
+
+**JSDoc:**
+
+```js
+/** @param {string} name */
+function greet(name) {
+  return "Hi, " + name;
+}
+```
+
+**TypeScript:**
+
+```ts
+function greet(name: string): string {
+  return "Hi, " + name;
+}
+```
+
+<!--v-->
+
+### Гибридный режим
+
+- `.js` + JSDoc + `tsconfig.json`
+- Получаем линтинг и автотипизацию без перехода на `.ts`
+
+<!--s-->
+
+## Генерация документации
+
+<!--v-->
+
+### С помощью JSDoc
+
+```bash
+npm install --save-dev jsdoc
+npx jsdoc src -r -d docs
+```
+
+- Генерирует HTML-документацию по комментариям
+
+<!--v-->
+
+### С помощью TypeDoc (для TS)
+
+```bash
+npm install --save-dev typedoc
+npx typedoc src
+```
+
+- Создаёт красивую документацию с ссылками между типами и интерфейсами
+
+<!--s-->
+
+## TypeScript для линтинга JS
+
+<!--v-->
+
+### Пример `tsconfig.json`
+
+```json
+{
+  "compilerOptions": {
+    "allowJs": true,
+    "checkJs": true,
+    "noEmit": true,
+    "strict": true
+  },
+  "include": ["src"]
+}
+```
+
+<!--v-->
+
+### Что даёт `checkJs`
+
+- TypeScript **проверяет** `.js` файлы
+- Учитывает типы из JSDoc
+- Показывает ошибки типов до выполнения
+
+<!--v-->
+
+### Пример ошибки:
+
+```js
+/** @param {number} x */
+function double(x) {
+  return x * "2"; // ❌ ошибка типов
+}
+```
+
+<!--s-->
+
+## Выводы
+
+<!--v-->
+
+- Документация = ясное API, а не просто комментарии
+- JSDoc помогает даже без TypeScript
+- TS усиливает надёжность и масштабируемость
+- Документацию можно генерировать автоматически
+- TypeScript умеет проверять `.js`-файлы с JSDoc
+
+<!--v-->
+
+### Вопросы? 🙋‍♀️🙋‍♂️

From 0243d9c5f3ee94feddc44696bac561b6945cc6a6 Mon Sep 17 00:00:00 2001
From: Evgeniya Bashieva <eugenia.bashieva@remago.com>
Date: Thu, 31 Jul 2025 18:52:32 +0200
Subject: [PATCH 2/2] fix: lint

---
 lessons/lesson12/lesson.md | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/lessons/lesson12/lesson.md b/lessons/lesson12/lesson.md
index 4c1f392..3e95244 100644
--- a/lessons/lesson12/lesson.md
+++ b/lessons/lesson12/lesson.md
@@ -32,9 +32,9 @@ description: "Работа с типами, JSDoc и TypeScript. Генерац
 - **Функции**: глаголы (`getUser`, `calculateTotal`)
 - **Модули**: предметная область (`authService`, `logger`)
 - **Переменные**:
-    - булевы: `isValid`, `hasPermission`
-    - коллекции: `users`, `items`
-    - константы: `MAX_LENGTH`, `DEFAULT_TIMEOUT`
+  - булевы: `isValid`, `hasPermission`
+  - коллекции: `users`, `items`
+  - константы: `MAX_LENGTH`, `DEFAULT_TIMEOUT`
 
 <!--v-->