docs: Обновление документации

Stivo182 · Stivo182 · commit 12d2948ee111 · 2025-06-26T00:27:50.000+03:00
diff --git a/docs/CLI.md b/docs/CLI.md
@@ -16,11 +16,11 @@ benchos run [OPTIONS] [FILE]
 | `--iterationTime` | Минимальное время выполнения одной итерации (мс) | `--iterationTime 500` |
 | `--warmupCount` | Количество прогревочных итераций | `--warmupCount 10` |
 | `--invocationCount` | Количество вызовов метода за итерацию | `--invocationCount 100` |
-| `--runtime` | Версии OneScript через запятую (current, stable, dev, x.x.x) | `--runtime dev,stable` |
+| `--runtime` | Версии OneScript через запятую (current, stable, dev, x.x.x). | `--runtime dev,stable` |
 | `--throughput` | Стратегия выполнения [`ПропускнаяСпособность`](СредаВыполнения.md#пропускнаяспособность) | |
 | `--coldstart` | Стратегия выполнения [`ХолодныйЗапуск`](СредаВыполнения.md#холодныйзапуск) | |
-| `-m`, `--memory` | Включить мониторинг использования памяти | |
-| `-e`, `--exporters` | Форматы экспорта результатов (`md`, `json`, `xml`, `html`) | `-e json,xml` |
+| `-m`, `--memory` | Включить [мониторинг использования памяти](МониторингПамяти.md) | |
+| `-e`, `--exporters` | Форматы [экспорта результатов](ЭкспортРезультатов.md) (`md`, `json`, `xml`, `html`) | `-e json,xml` |
 | `-a`, `--artifacts` | Каталог для сохранения результатов | `-a path/to/file` |
 | `-r`, `--recursive` | Рекурсивный поиск в поддиректориях | |
 | `-c`, `--config` | Файл конфигурации бенчмарков в формате JSON | `-c path/to/config.json` |
diff --git a/docs/README.md b/docs/README.md
@@ -1,20 +1,24 @@
 # Документация
 
-## Темы
+## Статьи
 - [Быстрый старт](БыстрыйСтарт.md)
 - [Запуск бенчмарков](ЗапускБенчмарков.md)
+- [CLI](CLI.md)
+- [Управление итерациями и вызовами](УправлениеИтерациямиИВызовами.md)
 - [Параметризация](Параметризация.md)
 - [Эталоны](Эталоны.md)
 - [Мониторинг памяти](МониторингПамяти.md)
-- [Обработчики событий](ОбработчикиСобытий.md)
-- [Статистика](Статистика.md)
-- [Сортировка отчета](СортировкаОтчета.md)
-- [Экспорт результатов](ЭкспортРезультатов.md)
+- [Метрики](Метрики.md)
 - [Среда выполнения](СредаВыполнения.md)
 - [Стратегии запуска](СтратегииЗапуска.md)
-- [CLI](CLI.md)
-- [Аннотации](../src/BenchmarkOneScript/annotations/Классы)
+- [Экспорт результатов](ЭкспортРезультатов.md)
+- [Обработчики событий](ОбработчикиСобытий.md)
+- [Сортировка отчета](СортировкаОтчета.md)
 
 ## Примеры
 - [Бенчмарки](../samples/benchmarks/Классы)
 - [API](../samples/api)
+
+## Прочее
+
+- [Аннотации](../src/BenchmarkOneScript/annotations/Классы)
diff --git a/docs/ЗапускБенчмарков.md b/docs/ЗапускБенчмарков.md
@@ -66,7 +66,7 @@ benchos run -r -m -e json ./benchmarks/
 Результат = Бенчмаркинг.ЗапуститьИзКаталога("/path/to/benchmarks", Истина);
 ```
 
-### Передача конфигурации
+### Запуск с передачей конфигурации
 
 ```bsl
 // Создание новой конфигурации
diff --git a/docs/Метрики.md b/docs/Метрики.md
@@ -1,4 +1,4 @@
-# Статистика
+# Метрики
 
 Для детального анализа производительности предусмотрено добавление специализированных статистических показателей.
 
diff --git a/docs/ОбработчикиСобытий.md b/docs/ОбработчикиСобытий.md
@@ -1,7 +1,7 @@
 # Обработчики событий
 
 Для изоляции логики подготовки и завершения от измеряемого кода реализован механизм обработчиков событий.
-Используйте специальные аннотации, чтобы определить методы, которые будут выполняться в разных фазах жизненного цикла бенчмарков: 
+Используйте специальные аннотации, чтобы определить методы, которые будут выполняться в разных фазах жизненного цикла бенчмарков.
 
 ## Конфигурирование 
 
diff --git a/docs/СортировкаОтчета.md b/docs/СортировкаОтчета.md
@@ -62,4 +62,3 @@
 | Быстрый   |         3 | 30.92 ms | 22.293 us |  86.34 us | 30.94 ms | 32.34 |
 | Медленный |         2 | 40.91 ms | 29.619 us | 114.71 us | 40.98 ms | 24.44 |
 | Медленный |         3 | 60.89 ms | 29.009 us | 112.35 us | 60.93 ms | 16.42 |
-
diff --git a/docs/СредаВыполнения.md b/docs/СредаВыполнения.md
@@ -49,17 +49,17 @@
 ```bsl
 Конфигурация
     .ДобавитьВерсиюИсполняющейСреды("1.9.3", "Стабильная сборка")
-    .ДобавитьВерсиюИсполняющейСреды("dev", "Ночная сборка")
+    .ДобавитьВерсиюИсполняющейСреды("dev", "Ночная сборка");
 ```
 
 3. Указание эталонной версии
 ```bsl
-Конфигурация.ДобавитьВерсиюИсполняющейСреды("stable", "Стабильная сборка", Истина)
+Конфигурация.ДобавитьВерсиюИсполняющейСреды("stable", "Стабильная сборка", Истина);
 ```
 
 4. Путь к исполняющему файлу
 ```bsl
-Конфигурация.ДобавитьВерсиюИсполняющейСреды("path/to/oscript.exe", "Моя сборка")
+Конфигурация.ДобавитьВерсиюИсполняющейСреды("path/to/oscript.exe", "Моя сборка");
 ```
 
 ### CLI
diff --git a/docs/СтратегииЗапуска.md b/docs/СтратегииЗапуска.md
@@ -17,7 +17,7 @@
 #### API
 
 ```bsl
-Конфигурация.УстановитьСтратегию(СтратегииЗапускаБенчмарка.ПропускнаяСпособность)
+Конфигурация.УстановитьСтратегию(СтратегииЗапускаБенчмарка.ПропускнаяСпособность);
 ```
 
 #### CLI
@@ -34,17 +34,17 @@ benchos run --throughput [FILE]
 
 ### Конфигурирование
 
-##### Аннотация
+#### Аннотация
 
 ```bsl
 &СтратегияХолодныйЗапуск
 Процедура ПриСозданииОбъекта()
 ```
 
-##### API
+#### API
 
 ```bsl
-Конфигурация.УстановитьСтратегию(СтратегииЗапускаБенчмарка.ХолодныйЗапуск)
+Конфигурация.УстановитьСтратегию(СтратегииЗапускаБенчмарка.ХолодныйЗапуск);
 ```
 
 #### CLI
diff --git a/docs/УправлениеИтерациямиИВызовами.md b/docs/УправлениеИтерациямиИВызовами.md
@@ -0,0 +1,138 @@
+# Управление итерациями и вызовами
+
+## Количество итераций
+
+Контролирует количество измерительных итераций для основных этапов (измерение и память).
+
+### Конфигурирование
+
+#### Аннотация
+
+```bsl
+&КоличествоИтераций(25)
+Процедура ПриСозданииОбъекта()
+```
+
+#### API
+
+```bsl
+Конфигурация.УстановитьКоличествоИтераций(25);
+```
+
+#### CLI
+
+```bash
+benchos run --iterationCount 25 [FILE]
+```
+
+
+## Количество вызовов за итерацию
+
+Указывает, сколько раз метод бенчмарка должен быть вызван в течение одной итерации. 
+
+Особенности:
+- Если установлено `0`, то количество будет рассчитано автоматически.
+- Игнорируется для стратегии [`ХолодныйЗапуск`](СредаВыполнения.md#холодныйзапуск).
+
+### Конфигурирование
+
+#### Аннотация
+
+```bsl
+&КоличествоВызововЗаИтерацию(1000)
+Процедура ПриСозданииОбъекта()
+```
+
+#### API
+
+```bsl
+Конфигурация.УстановитьКоличествоВызововЗаИтерацию(1000);
+```
+
+#### CLI
+
+```bash
+benchos run --invocationCount 1000 [FILE]
+```
+
+
+## Количество прогревочных итераций
+
+Указывает количество прогревочных итераций для подготовки окружения перед выполнением основных замеров бенчмарка. Прогревочные итерации используются для стабилизации системы: прогрев кэшей, 
+инициализация внешних ресурсов. Результаты этих итераций не учитываются в финальной статистике. 
+
+Особенности:
+- Игнорируется для стратегии [`ХолодныйЗапуск`](СредаВыполнения.md#холодныйзапуск).
+
+### Конфигурирование
+
+#### Аннотация
+
+```bsl
+&КоличествоПрогревочныхИтераций(10)
+Процедура ПриСозданииОбъекта()
+```
+
+#### API
+
+```bsl
+Конфигурация.УстановитьКоличествоПрогревочныхИтераций(10);
+```
+
+#### CLI
+
+```bash
+benchos run --warmupCount 10 [FILE]
+```
+
+
+## Минимальное время итерации
+
+Указывает минимальное время выполнения одной итерации бенчмарка в миллисекундах. Используется для подбора количества вызовов за итерацию так, чтобы одна итерация длилась не меньше указанного времени.
+
+Особенности:
+- Игнорируется для стратегии [`ХолодныйЗапуск`](СредаВыполнения.md#холодныйзапуск).
+
+### Конфигурирование
+
+#### Аннотация
+
+```bsl
+&МинимальноеВремяИтерации(250)
+Процедура ПриСозданииОбъекта()
+```
+
+#### API
+
+```bsl
+Конфигурация.УстановитьМинимальноеВремяИтерации(250);
+```
+
+#### CLI
+
+```bash
+benchos run --iterationTime 250 [FILE]
+```
+
+
+## Минимальное количество вызовов за итерацию
+
+Гарантированное мминимальное количество вызовов метода в течение одной итерации бенчмарка.
+
+Особенности:
+- Игнорируется для стратегии [`ХолодныйЗапуск`](СредаВыполнения.md#холодныйзапуск).
+
+### Конфигурирование
+
+#### Аннотация
+
+```bsl
+&МинимальноеКоличествоВызововЗаИтерацию(8)
+Процедура ПриСозданииОбъекта()
+```
+
+#### API
+
+```bsl
+Конфигурация.УстановитьМинимальноеКоличествоВызововЗаИтерацию(8);
+```
diff --git a/docs/ЭкспортРезультатов.md b/docs/ЭкспортРезультатов.md
@@ -17,7 +17,7 @@
 2. Программно с использованием API конфигурации:
 
 ```bsl
-Конфигурация.УстановитьКаталогАртефактов("path/to/artifacts")
+Конфигурация.УстановитьКаталогАртефактов("path/to/artifacts");
 ```
 
 ### Аннотации экспортеров
diff --git a/docs/Эталоны.md b/docs/Эталоны.md
@@ -159,6 +159,33 @@
 
 Принцип интерпретации: **чем выше значение `RatioSD`, тем больше вариативность результатов**, что указывает на потенциальные проблемы в воспроизводимости тестирования. 
 
-## Эталонные версии исполняющей среды
 
-Подробнее см. в разделе [Среда выполнения](СредаВыполнения.md).
+## Эталонные среды выполнения
+
+### Конфигурирование
+
+#### Аннотация
+
+```bsl
+&ИсполняющаяСреда(
+    Версия = "1.9.3", 
+    Наименование = "Стабильная сборка",
+    ЭтоЭталон = Истина
+)
+Процедура ПриСозданииОбъекта()
+```
+
+#### API
+
+```bsl
+Конфигурация.ДобавитьВерсиюИсполняющейСреды("stable", "Стабильная сборка", Истина);
+```
+
+### Пример выполнения
+
+| Method | Runtime               | Baseline |      Mean |   StdErr |   StdDev | Ratio | RatioSD |    Op/s |
+|--------|-----------------------|----------|----------:|---------:|---------:|------:|--------:|--------:|
+| SHA256 | 2.0.0-rc.8+608        | No       |  9.048 us | 93.81 ns | 363.3 ns |  0.67 |    0.03 | 110,523 |
+| SHA256 | Стабильная (1.9.3.15) | Yes      | 13.561 us | 70.97 ns | 274.9 ns |  1.00 |    0.00 |  73,742 |
+
+Подробнее см. в разделе [Среда выполнения](СредаВыполнения.md)
diff --git a/samples/api/ДобавлениеКолонкиОтчетаПример.os b/samples/api/ДобавлениеКолонкиОтчетаПример.os
@@ -1,6 +1,3 @@
-// BSLLS:MagicNumber-off
-// BSLLS:CommentedCode-off
-
 #Использовать benchmark
 #Использовать "../benchmarks"
 
@@ -10,6 +7,6 @@
 Конфигурация.ДобавитьКолонку(КолонкиОтчетаБенчмарков.Мин);
 Конфигурация.ДобавитьКолонку(КолонкиОтчетаБенчмарков.Макс);
 Конфигурация.ДобавитьКолонку(КолонкиОтчетаБенчмарков.Процентиль(33)); // 33-й процентиль
-//Конфигурация.ДобавитьКолонку(КолонкиОтчетаБенчмарков.Процентиль); // Процентили по умолчанию
+//Конфигурация.ДобавитьКолонку(КолонкиОтчетаБенчмарков.Процентиль); // Стандартный набор процентилей
 
 Бенчмаркинг.Запустить(Тип, Конфигурация);
diff --git a/src/BenchmarkOneScript/annotations/Классы/АннотацияКоличествоВызововЗаИтерацию.os b/src/BenchmarkOneScript/annotations/Классы/АннотацияКоличествоВызововЗаИтерацию.os
@@ -5,6 +5,7 @@
 //
 // - Применяется только к методу ПриСозданииОбъекта
 // - Если установлено "0", то количество будет рассчитано автоматически
+// - Игнорируется для стратегии "ХолодныйЗапуск"
 //
 // Примеры:
 //   &КоличествоВызововЗаИтерацию(100)
diff --git a/src/BenchmarkOneScript/core/Классы/КонфигурацияБенчмарков.os b/src/BenchmarkOneScript/core/Классы/КонфигурацияБенчмарков.os
@@ -111,7 +111,8 @@
 // Используется для увеличения времени выполнения итерации, что повышает точность измерений
 // для методов с очень быстрым временем выполнения.
 //
-// Если установлено "0", то количество будет рассчитано автоматически.
+// - Если установлено "0", то количество будет рассчитано автоматически.
+// - Игнорируется для стратегии "ХолодныйЗапуск".
 //
 // Параметры:
 //   КоличествоВызововЗаИтерацию - Число

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Статистика`
	`1`	`+# Метрики`
`2`	`2`
`3`	`3`	`Для детального анализа производительности предусмотрено добавление специализированных статистических показателей.`
`4`	`4`