Skip to content

Commit 50dd464

Browse files
authored
Merge pull request #220 from Infarh/dev
v0.0.16 - Обновление MathCore. Доработка XML-документации.
2 parents a751826 + 0568d41 commit 50dd464

File tree

15 files changed

+1963
-27
lines changed

15 files changed

+1963
-27
lines changed
Lines changed: 76 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,76 @@
1+
---
2+
name: auditAndDocumentModule
3+
---
4+
5+
Проведите комплексную ревизию и документирование указанного модуля или пространства имён. Выполните следующие задачи:
6+
7+
## 1. Создание архитектурной документации
8+
9+
Напишите полный README.md файл, включающий:
10+
- **Основные возможности** - список ключевых функций модуля
11+
- **Архитектура** - описание всех основных компонентов с диаграммами/схемами
12+
- **Основной цикл обработки** - блок-схема или текстовое описание потока данных
13+
- **Примеры использования** - базовые и продвинутые примеры с кодом
14+
- **Поддерживаемая функциональность** - список команд, методов, свойств
15+
- **Конфигурация** - описание файлов и параметров конфигурации
16+
- **Точки расширения** - как добавлять новые функции
17+
- **Производительность** - рекомендации по оптимизации
18+
- **Обработка ошибок** - описание исключений и их причин
19+
20+
## 2. Добавление XML-документации
21+
22+
Для всех публичных типов и методов добавьте:
23+
- `<summary>` - краткое описание (одна строка)
24+
- `<remarks>` - подробное объяснение (многострочное)
25+
- `<param>` - описание параметров с типами
26+
- `<returns>` - описание возвращаемого значения
27+
- `<exception>` - выбрасываемые исключения
28+
- `<example>` - практические примеры использования в блоке `<![CDATA[]]>`
29+
30+
## 3. Локализация комментариев
31+
32+
Переведите все комментарии в коде на целевой язык (указать в инструкции):
33+
- Встроенные однострочные комментарии
34+
- Многострочные блочные комментарии
35+
- Сохраняйте техническую терминологию в том же языке (CamelCase имена, аббревиатуры)
36+
37+
## 4. Ревизия качества кода
38+
39+
Проанализируйте код на:
40+
- Ошибки компиляции и синтаксические проблемы
41+
- Потенциальные ошибки в реализации
42+
- Нарушения принципов SOLID
43+
- Проблемы с обработкой исключений
44+
- Неиспользуемый код
45+
- Архитектурные проблемы
46+
47+
## 5. Управление версионированием (Git)
48+
49+
Выполните следующий рабочий процесс:
50+
- Создайте feature-ветку (например, `feature/module-review-and-docs`)
51+
- Добавьте и закоммитьте все изменения с описательными сообщениями
52+
- Переключитесь на целевую ветку (обычно `dev`)
53+
- Выполните merge feature-ветки в целевую ветку
54+
- Удалите временную feature-ветку
55+
- Проверьте успешную интеграцию
56+
57+
## 6. Итоговый отчёт
58+
59+
Создайте отчёт, включающий:
60+
- Список всех модифицированных файлов
61+
- Количество добавленных и удаленных строк
62+
- Краткое описание каждого изменения
63+
- Выявленные проблемы (если есть)
64+
- Рекомендации по дальнейшему улучшению
65+
- Git информацию (ветка, commit ID, статистика merge)
66+
67+
## Контрольный список
68+
69+
- [ ] Проект успешно компилируется
70+
- [ ] README.md создан и содержит полную документацию
71+
- [ ] XML-комментарии добавлены ко всем публичным членам
72+
- [ ] Все комментарии переведены на целевой язык
73+
- [ ] Примеры кода заключены в блоки CDATA
74+
- [ ] Проведена ревизия качества кода
75+
- [ ] Git операции выполнены успешно
76+
- [ ] Итоговый отчёт составлен
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
1+
---
2+
name: documentPublicApi
3+
---
4+
# Документирование публичного API
5+
6+
Проверь и дополни файл полной XML-документацией для типа (класса, интерфейса, структуры) и всех его публичных членов.
7+
8+
## Документирование класса/типа
9+
10+
Добавь комментарий к самому классу/типу с:
11+
- `<summary>` — краткое описание назначения и функциональности
12+
- `<remarks>` — дополнительная информация о возможностях и ограничениях (опционально)
13+
- `<example>` — практический пример, демонстрирующий основные сценарии использования класса
14+
15+
## Документирование публичных членов
16+
17+
Убедись, что все публичные члены задокументированы — методы, свойства, события, события должны иметь полный набор тегов:
18+
- `<summary>` — краткое описание (одна строка, без точки в конце)
19+
- `<param>` — для параметров методов (если они есть)
20+
- `<returns>` — для возвращаемого значения
21+
- `<value>` — для свойств, описывающее значение
22+
- `<exception>` — для исключений, которые может выбросить метод
23+
- `<remarks>` — дополнительная информация (опционально)
24+
- `<example>` — примеры использования для сложных публичных методов
25+
26+
## Требования к комментариям
27+
28+
1. **Язык:** все комментарии на русском языке — переведи существующие английские комментарии
29+
2. **Примеры использования:**
30+
- Добавь блок `<example>` с практическим примером кода
31+
- Обёрнь код в `<code language="csharp"><![CDATA[ ... ]]></code>`
32+
- Для класса: покажи типичные сценарии использования его основной функциональности
33+
- Для методов: продемонстрируй типичный вызов и результат
34+
3. **Структура:**
35+
- Порядок тегов: `<summary>``<param>``<returns>``<value>``<exception>``<remarks>``<example>`
36+
- Каждый тег на отдельной строке
37+
- Одинарное предложение в одной строке без точки в конце внутри тега
38+
39+
## Минимизация изменений
40+
41+
Изменяй только документацию — не переписывай существующий код, не добавляй новые члены класса, не рефакторь реализацию.

.github/workflows/publish.yml

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -22,17 +22,17 @@ jobs:
2222

2323
steps:
2424
- name: Checkout
25-
uses: actions/checkout@v4
25+
uses: actions/checkout@v6
2626
with:
2727
fetch-depth: 0
2828

2929
- name: Setup .NET
30-
uses: actions/setup-dotnet@v4
30+
uses: actions/setup-dotnet@v5
3131
with:
3232
dotnet-version: 10.0.x
3333

3434
- name: Cache NuGet
35-
uses: actions/cache@v4
35+
uses: actions/cache@v5
3636
with:
3737
path: ~/.nuget/packages
3838
key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}
@@ -56,7 +56,7 @@ jobs:
5656
run: dotnet pack MathCore.DSP --no-build -c Release -v q -o ${{ github.workspace }}/ReleasePack --include-symbols
5757

5858
- name: Upload build artifacts
59-
uses: actions/upload-artifact@v4.6.0
59+
uses: actions/upload-artifact@v6.0.0
6060
with:
6161
name: Release
6262
path: ${{ github.workspace }}/ReleasePack
@@ -69,7 +69,7 @@ jobs:
6969

7070
steps:
7171
- name: Get artifact
72-
uses: actions/download-artifact@v4.1.7
72+
uses: actions/download-artifact@v7.0.0
7373
id: download
7474
with:
7575
name: Release
@@ -85,7 +85,7 @@ jobs:
8585

8686
steps:
8787
- name: Get artifact
88-
uses: actions/download-artifact@v4.1.7
88+
uses: actions/download-artifact@v7.0.0
8989
id: download
9090
with:
9191
name: Release

.github/workflows/testing.yml

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -21,17 +21,17 @@ jobs:
2121
runs-on: ubuntu-latest
2222

2323
steps:
24-
- uses: actions/checkout@v4
24+
- uses: actions/checkout@v6
2525
with:
2626
fetch-depth: 0
2727

2828
- name: Setup .NET
29-
uses: actions/setup-dotnet@v4
29+
uses: actions/setup-dotnet@v5
3030
with:
3131
dotnet-version: 10.0.x
3232

3333
- name: Cache NuGet
34-
uses: actions/cache@v4
34+
uses: actions/cache@v5
3535
with:
3636
path: ~/.nuget/packages
3737
key: ${{ runner.os }}-nuget-${{ hashFiles('**/packages.lock.json') }}

.scripts/nuget-ver-remote.cs

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
#!/usr/local/bin/dotnet run
2+
// Файл file-based app скрипта для определения текущей версии NuGet пакета из удаленного репозитория.
3+
// Использование: dotnet run .scripts/nuget-ver-remote.cs <package-name>
4+
5+
#nullable enable
6+
7+
#:package NuGet.Protocol@7.0.1
8+
#:package NuGet.Configuration@7.0.1
9+
10+
using System;
11+
using System.Linq;
12+
using System.Threading;
13+
using System.Threading.Tasks;
14+
using NuGet.Common;
15+
using NuGet.Configuration;
16+
using NuGet.Protocol;
17+
using NuGet.Protocol.Core.Types;
18+
using NuGet.Versioning;
19+
20+
if (args.Length < 1)
21+
{
22+
Console.Error.WriteLine("Usage: dotnet run .scripts/nuget-ver-remote.cs <package-name>");
23+
Environment.Exit(1);
24+
}
25+
26+
var package_name = args[0]; // имя пакета из аргумента
27+
if (string.IsNullOrWhiteSpace(package_name))
28+
{
29+
Console.Error.WriteLine("Package name is empty");
30+
Environment.Exit(1);
31+
}
32+
33+
try
34+
{
35+
// Создадим репозиторий NuGet (v3 API)
36+
var source_repo = Repository.Factory.GetCoreV3("https://api.nuget.org/v3/index.json");
37+
38+
// Получим ресурс метаданных пакета
39+
using var cache = new SourceCacheContext();
40+
var logger = NullLogger.Instance;
41+
var resource = await source_repo.GetResourceAsync<PackageMetadataResource>().ConfigureAwait(false);
42+
43+
// Запросим все метаданные по пакету (включая pre-release), не включая unlisted
44+
var metadata = await resource.GetMetadataAsync(package_name, includePrerelease: true, includeUnlisted: false, cache, logger, CancellationToken.None).ConfigureAwait(false);
45+
46+
var metadata_list = metadata?.ToList() ?? new System.Collections.Generic.List<IPackageSearchMetadata>();
47+
if (metadata_list.Count == 0)
48+
{
49+
Console.Error.WriteLine($"Package not found: {package_name}");
50+
Environment.Exit(2);
51+
}
52+
53+
// Соберём версии и выберем последнюю стабильную, если есть, иначе последнюю доступную
54+
var versions = metadata_list
55+
.Select(m => m.Identity.Version)
56+
.Where(v => v is not null)
57+
.OrderBy(v => v)
58+
.ToArray();
59+
60+
if (versions.Length == 0)
61+
{
62+
Console.Error.WriteLine("No versions found");
63+
Environment.Exit(2);
64+
}
65+
66+
var stable_version = versions
67+
.Where(v => !v.IsPrerelease)
68+
.OrderByDescending(v => v)
69+
.FirstOrDefault()
70+
?? versions.OrderByDescending(v => v).First();
71+
72+
var latest_version = stable_version.ToNormalizedString();
73+
74+
Console.WriteLine(latest_version); // вывод версии в stdout
75+
Environment.Exit(0);
76+
}
77+
catch (Exception ex)
78+
{
79+
Console.Error.WriteLine($"Error: {ex.Message}");
80+
Environment.Exit(2);
81+
}

.scripts/nuget-ver-wait.cs

Lines changed: 116 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,116 @@
1+
#!/usr/local/bin/dotnet run
2+
// Файл file-based app скрипта для ожидания появления указанной версии NuGet пакета на сервере.
3+
// Использование: dotnet run .scripts/nuget-ver-wait.cs <package-name> <target-version> [-n <tries>] [-t <timeout-ms>]
4+
5+
#nullable enable
6+
7+
#:package NuGet.Protocol@7.0.1
8+
#:package NuGet.Configuration@7.0.1
9+
10+
using System;
11+
using System.Linq;
12+
using System.Threading;
13+
using System.Threading.Tasks;
14+
using NuGet.Common;
15+
using NuGet.Configuration;
16+
using NuGet.Protocol;
17+
using NuGet.Protocol.Core.Types;
18+
using NuGet.Versioning;
19+
20+
if (args.Length < 2)
21+
{
22+
Console.Error.WriteLine("Usage: dotnet run .scripts/nuget-ver-wait.cs <package-name> <target-version> [-n <tries>] [-t <timeout-ms>]");
23+
Environment.Exit(1);
24+
}
25+
26+
var package_name = args[0]; // имя пакета
27+
var target_version_str = args[1]; // требуемая версия
28+
if (string.IsNullOrWhiteSpace(package_name) || string.IsNullOrWhiteSpace(target_version_str))
29+
{
30+
Console.Error.WriteLine("Package name or target version is empty");
31+
Environment.Exit(1);
32+
}
33+
34+
// Значения по умолчанию
35+
var tries = 10; // -n по умолчанию
36+
var timeout_ms = 1000; // -t по умолчанию
37+
38+
// Разбор дополнительных аргументов
39+
for (var i = 2; i < args.Length; i++)
40+
{
41+
var a = args[i];
42+
const StringComparison cmp = StringComparison.OrdinalIgnoreCase;
43+
if (string.Equals(a, "-n", cmp) && i + 1 < args.Length)
44+
{
45+
if (int.TryParse(args[++i], out var v)) tries = v;
46+
}
47+
else if (string.Equals(a, "-t", cmp) && i + 1 < args.Length)
48+
{
49+
if (int.TryParse(args[++i], out var v)) timeout_ms = v;
50+
}
51+
}
52+
53+
if (tries <= 0) tries = 1;
54+
if (timeout_ms < 0) timeout_ms = 0;
55+
56+
if (!NuGetVersion.TryParse(target_version_str, out var target_version))
57+
{
58+
Console.Error.WriteLine($"Невозможно распарсить целевую версию: {target_version_str}");
59+
Environment.Exit(1);
60+
}
61+
62+
Console.WriteLine($"Ожидание версии {target_version} пакета {package_name} на nuget.org ({tries} попыток, таймаут {timeout_ms}ms)");
63+
64+
try
65+
{
66+
var source_repo = Repository.Factory.GetCoreV3("https://api.nuget.org/v3/index.json");
67+
using var cache = new SourceCacheContext();
68+
var logger = NullLogger.Instance;
69+
var resource = await source_repo.GetResourceAsync<PackageMetadataResource>();
70+
71+
for (var attempt = 1; attempt <= tries; attempt++)
72+
{
73+
// Получим метаданные пакета
74+
var metadata = await resource.GetMetadataAsync(package_name, includePrerelease: true, includeUnlisted: false, cache, logger, CancellationToken.None);
75+
var metadata_list = metadata?.ToList() ?? [];
76+
77+
if (metadata_list.Count == 0)
78+
Console.WriteLine($"[{attempt}/{tries}] Пакет не найден на сервере");
79+
else
80+
{
81+
var versions = metadata_list
82+
.Select(m => m.Identity.Version)
83+
.Where(v => v is not null)
84+
.OrderByDescending(v => v)
85+
.ToArray();
86+
87+
if (versions.Length == 0)
88+
Console.WriteLine($"[{attempt}/{tries}] На сервере нет версий пакета");
89+
else
90+
{
91+
var latest = versions[0];
92+
Console.WriteLine($"[{attempt}/{tries}] Серверная последняя версия: {latest}");
93+
94+
// Сравним последнюю серверную версию с целевой
95+
if (latest < target_version)
96+
Console.WriteLine($"Серверная версия {latest} младше требуемой {target_version}, ожидаем...");
97+
else
98+
{
99+
Console.WriteLine($"Требуемая версия {target_version} доступна на сервере (серверная версия {latest})");
100+
Environment.Exit(0);
101+
}
102+
}
103+
}
104+
105+
if (attempt < tries)
106+
await Task.Delay(timeout_ms);
107+
}
108+
109+
Console.Error.WriteLine($"Не удалось дождаться версии {target_version} для пакета {package_name} после {tries} попыток");
110+
Environment.Exit(2);
111+
}
112+
catch (Exception ex)
113+
{
114+
Console.Error.WriteLine($"Ошибка: {ex.Message}");
115+
Environment.Exit(2);
116+
}

0 commit comments

Comments
 (0)