docs: актуализация документации проекта (.NET 8, корректные пути, дописанные разделы)#1669
Merged
EvilBeaver merged 1 commit intoEvilBeaver:developfrom Apr 30, 2026
Merged
Conversation
…ктуру кода - README.md / README-EN.md: убрано устаревшее упоминание .net6 (фактический таргет — net8.0), команды переведены на `dotnet msbuild`; добавлены отсутствовавшие таргеты `GatherLibrary`, `Test`, `UnitTests`, `ScriptedTests`, `PublishNuget` и параметры `NoCppCompiler`, `Configuration`; добавлены разделы «Тестирование» (с командами для модульных C# и приёмочных BSL-тестов через tests/run-bsl-tests.*) и «Документация для разработчиков» со ссылками на docs/ и CODESTYLE.md. Русская и английская версии приведены к одинаковой структуре. - docs/developer_docs.md: починена поломанная нумерация разделов (3.1–3.4, 7., 3.6–3.10 → последовательно 3.1–3.10), убран дубль заголовка в разделе про OneScript.Core, уточнены реальные пути к файлам (PreprocessingLexer.cs и LocalizedErrors.cs — в SyntaxAnalysis/; CompilerBackendSelector вместо BackendSelector; ExecutionFrame вместо Frame; ValueList/, ValueTable/, ValueTree/ как подкаталоги Collections/; актуальные классы OneScript.DebugServices и StandaloneRunner), исправлена опечатка ContextValuesMarhaller → ContextValuesMarshaller, добавлены ссылки на README.md, contexts.md, CODESTYLE.md и .github/copilot-instructions.md. - docs/contexts.md: починена битая ссылка docs/arhitecture_overview.md → docs/developer_docs.md; заголовки приведены к markdown-разметке; оглавление сделано кликабельным; дописаны обещанные в содержании, но отсутствовавшие разделы (i18n для API, Депрекейшен и едупреждения, Тестирование C# и BSL, Документация (OneScriptDocumenter), Безопасность, Чек-лист готовности). В C#-шаблонах исправлены using-и: `OneScript.Execution` вместо несуществующего `OneScript.Core.Execution`, добавлен `ScriptEngine.Machine` для IValue/ValueFactory; сверено с живыми контекстами из OneScript.StandardLibrary.
Contributor
📝 WalkthroughWalkthroughDocumentation across four markdown files updated to clarify .NET SDK 8.0 requirements, C++ compiler usage for native components, build targets via dotnet msbuild, and expanded sections covering testing procedures, developer documentation, context implementation guidance, and project architecture details. Changes
Estimated code review effort🎯 2 (Simple) | ⏱️ ~12 minutes Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.Comment |
Contributor
Author
|
@EvilBeaver посмотришь pr? |
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
Contributor
There was a problem hiding this comment.
🧹 Nitpick comments (6)
docs/contexts.md (1)
3-6: Minor doc polish: make the “См. также” link text match the href target.In
docs/contexts.mdyou have:
- link text:
docs/developer_docs.md- href:
developer_docs.md(relative to the currentdocs/folder)The href works, but the visible text is inconsistent. Consider changing either the text to
developer_docs.mdor the href to../docs/developer_docs.md(though the latter is unnecessary from withindocs/).🛠️ Suggested diff
-См. также [`docs/developer_docs.md`](developer_docs.md) — карта компонентов и «куда лезть» при доработках. +См. также [`developer_docs.md`](developer_docs.md) — карта компонентов и «куда лезть» при доработках.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/contexts.md` around lines 3 - 6, Update the link text in docs/contexts.md so the visible text matches the href: change the link text `docs/developer_docs.md` to `developer_docs.md` (the href is already `developer_docs.md`), ensuring the markdown link [developer_docs.md](developer_docs.md) replaces the current mismatched version; locate the Markdown link in the top section where the "См. также" reference appears and make this single-line text change.docs/developer_docs.md (1)
5-10: Minor doc polish: make the “См. также” link text match the href target.Similar to
docs/contexts.md, this file shows link textdocs/contexts.mdbut the href iscontexts.md(relative withindocs/). The link likely resolves, but the visible text is misleading.🛠️ Suggested diff
-- [`docs/contexts.md`](contexts.md) — практическое руководство по добавлению BSL-контекстов и глобальных методов; +- [`contexts.md`](contexts.md) — практическое руководство по добавлению BSL-контекстов и глобальных методов;🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@docs/developer_docs.md` around lines 5 - 10, Update the visible link text in the "См. также:" list so it matches the actual href target: change the link text "docs/contexts.md" to "contexts.md" (or adjust the href to ../docs/contexts.md if you prefer the longer form) so the displayed text and the href are identical; edit the list item containing [`docs/contexts.md`](contexts.md) to ensure consistency between link label and target.README.md (2)
122-145: Clarify that BSL runner paths assumeDebugoutput (UX correctness).The wrapper commands hardcode
.../bin/Debug/net8.0/.... The doc later says to rundotnet build src/oscript/oscript.csprojbefore acceptance tests—by default that buildsDebug, so it works—but it will silently break if someone earlier builds withRelease/LinuxDebug.Add a short note that these paths correspond to the default
Debugconfiguration, or point users to adjust the path to match theirConfiguration.🛠️ Suggested diff
Before running the acceptance tests, build `oscript`: ```bat dotnet build src/oscript/oscript.csproj
- (По умолчанию это сборка в
Debug; если использовали другую конфигурацию — укажите её и корректируйте путь кoscriptв командах-обёртках.)</details> <details> <summary>🤖 Prompt for AI Agents</summary>Verify each finding against the current code and only fix it if needed.
In
@README.mdaround lines 122 - 145, The README's BSL runner wrapper commands
hardcode the Debug output path (src/oscript/bin/Debug/net8.0/oscript), which
will break if users build in a different Configuration; update the Testing
section to add a short note after the dotnet build instruction explaining that
the example wrappers (tests\run-bsl-tests.cmd and tests/run-bsl-tests.sh) assume
the default Debug configuration and instruct users to adjust the path to the
oscript binary if they built with a different Configuration (e.g., Release) or
custom RID/TFM.</details> --- `67-153`: **MD003: normalize heading “atx_closed” style across updated headings (optional).** The provided static analysis hints indicate MD003 “Heading style — Expected: atx_closed; Actual: atx” for multiple headings in this section (e.g., “## Build”, several “### …”, and “# Тестирование” / “# Документация для разработчиков”). If your lint config expects closed ATX headings, update these headings to include closing hashes. <details> <summary>🛠️ Suggested diff (pattern example)</summary> ```diff -## Build +## Build ## -### Building distribution contents in a separate directory +### Building distribution contents in a separate directory ## -### Building with manual version specification +### Building with manual version specification ## -### Building ZIP distributions +### Building ZIP distributions ## -### Building without C++-components (no NativeApi) +### Building without C++-components (no NativeApi) ## -### Documentation generation +### Documentation generation ## -# Тестирование +# Тестирование # -# Документация для разработчиков +# Документация для разработчиков #🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README.md` around lines 67 - 153, Update headings to closed ATX style by adding trailing hashes so they match the lint rule MD003; specifically change headings such as "## Сборка", "### Сборка содержимого дистрибутивов в отдельном каталоге", "### Сборка с ручным указанием версии", "### Сборка ZIP-дистрибутивов", "### Сборка без C++-компонент (без NativeApi)", "### Генерация документации", "# Тестирование", and "# Документация для разработчиков" (and any other headings in this modified block) to include closing hashes (e.g., "## Сборка ##") so all ATX headings in this section are consistently atx_closed.README-EN.md (2)
122-145: Clarify BSL runner paths assumeDebugoutput (UX correctness).The BSL acceptance test wrapper commands reference
.../bin/Debug/net8.0/oscript(.exe). That matchesdotnet builddefault configuration, but it won’t match if the user buildsoscriptwithReleaseor anotherConfiguration.Add a short note to adjust the wrapper path (or build
oscriptin Debug) based on theConfigurationused.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README-EN.md` around lines 122 - 145, Update the Testing section to note that the BSL acceptance test wrapper commands (tests\run-bsl-tests.cmd and tests/run-bsl-tests.sh) point to bin/Debug/net8.0/oscript(.exe) which assumes a Debug build; instruct readers to either build oscript in Debug (dotnet build src/oscript/oscript.csproj) or update the wrapper paths to match their chosen Configuration/target (e.g., Release/bin/Release/net8.0/oscript(.exe)).
67-154: MD003: normalize heading “atx_closed” style across updated headings (optional).The provided static analysis hints indicate MD003 “heading-style” issues for the same set of headings in README-EN.md (e.g., “## Build”, several “### …”, and “# Testing” / “# Developer documentation”). If your markdownlint configuration expects closed ATX headings, update them to the
## Heading ##/# Heading #form to match the expectation.🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@README-EN.md` around lines 67 - 154, Update README-EN.md to use closed ATX headings to satisfy MD003: change headings like "## Build", all "### ..." subsection headings (e.g., "### Building distribution contents in a separate directory", "### Building ZIP distributions", "### Documentation generation"), and top-level headings " # Testing" and "# Developer documentation" to the closed form with trailing hashes (for example "## Build ##", "### Building distribution contents in a separate directory ###", "# Testing #", "# Developer documentation #"); apply this consistently across the file and re-run markdownlint to confirm MD003 is resolved.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Nitpick comments:
In `@docs/contexts.md`:
- Around line 3-6: Update the link text in docs/contexts.md so the visible text
matches the href: change the link text `docs/developer_docs.md` to
`developer_docs.md` (the href is already `developer_docs.md`), ensuring the
markdown link [developer_docs.md](developer_docs.md) replaces the current
mismatched version; locate the Markdown link in the top section where the "См.
также" reference appears and make this single-line text change.
In `@docs/developer_docs.md`:
- Around line 5-10: Update the visible link text in the "См. также:" list so it
matches the actual href target: change the link text "docs/contexts.md" to
"contexts.md" (or adjust the href to ../docs/contexts.md if you prefer the
longer form) so the displayed text and the href are identical; edit the list
item containing [`docs/contexts.md`](contexts.md) to ensure consistency between
link label and target.
In `@README-EN.md`:
- Around line 122-145: Update the Testing section to note that the BSL
acceptance test wrapper commands (tests\run-bsl-tests.cmd and
tests/run-bsl-tests.sh) point to bin/Debug/net8.0/oscript(.exe) which assumes a
Debug build; instruct readers to either build oscript in Debug (dotnet build
src/oscript/oscript.csproj) or update the wrapper paths to match their chosen
Configuration/target (e.g., Release/bin/Release/net8.0/oscript(.exe)).
- Around line 67-154: Update README-EN.md to use closed ATX headings to satisfy
MD003: change headings like "## Build", all "### ..." subsection headings (e.g.,
"### Building distribution contents in a separate directory", "### Building ZIP
distributions", "### Documentation generation"), and top-level headings " #
Testing" and "# Developer documentation" to the closed form with trailing hashes
(for example "## Build ##", "### Building distribution contents in a separate
directory ###", "# Testing #", "# Developer documentation #"); apply this
consistently across the file and re-run markdownlint to confirm MD003 is
resolved.
In `@README.md`:
- Around line 122-145: The README's BSL runner wrapper commands hardcode the
Debug output path (src/oscript/bin/Debug/net8.0/oscript), which will break if
users build in a different Configuration; update the Testing section to add a
short note after the dotnet build instruction explaining that the example
wrappers (tests\run-bsl-tests.cmd and tests/run-bsl-tests.sh) assume the default
Debug configuration and instruct users to adjust the path to the oscript binary
if they built with a different Configuration (e.g., Release) or custom RID/TFM.
- Around line 67-153: Update headings to closed ATX style by adding trailing
hashes so they match the lint rule MD003; specifically change headings such as
"## Сборка", "### Сборка содержимого дистрибутивов в отдельном каталоге", "###
Сборка с ручным указанием версии", "### Сборка ZIP-дистрибутивов", "### Сборка
без C++-компонент (без NativeApi)", "### Генерация документации", "#
Тестирование", and "# Документация для разработчиков" (and any other headings in
this modified block) to include closing hashes (e.g., "## Сборка ##") so all ATX
headings in this section are consistently atx_closed.
ℹ️ Review info
⚙️ Run configuration
Configuration used: defaults
Review profile: CHILL
Plan: Pro
Run ID: 810b4a49-6a71-4d5f-84b4-e584ac1645b6
📒 Files selected for processing (4)
README-EN.mdREADME.mddocs/contexts.mddocs/developer_docs.md
EvilBeaver
approved these changes
Apr 29, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
(реальный target —
net8.0), команды переведены наdotnet msbuild,добавлены недостающие таргеты (
GatherLibrary,Test,UnitTests,ScriptedTests,PublishNuget) и параметры (NoCppCompiler,Configuration), добавлены разделы «Тестирование» и «Документациядля разработчиков». Русская и английская версии полностью
синхронизированы (одинаковая структура из 19 заголовков).
(3.1–3.4, 7., 3.6–3.10 → последовательная 3.1–3.10), убраны дубли
заголовков, исправлены реальные пути и имена файлов
(
PreprocessingLexer.cs/LocalizedErrors.csвSyntaxAnalysis/,CompilerBackendSelector,ExecutionFrame, подкаталогиValueList/,ValueTable/,ValueTree/, актуальные классыOneScript.DebugServicesи
StandaloneRunner), исправлена опечаткаContextValuesMarhaller→
ContextValuesMarshaller, добавлены перекрёстные ссылки наREADME.md,contexts.md,CODESTYLE.md,.github/copilot-instructions.md.docs/arhitecture_overview.md→docs/developer_docs.md, заголовкиприведены к markdown-разметке, оглавление сделано кликабельным;
дописаны заявленные, но отсутствовавшие разделы (i18n для API,
Депрекейшен и предупреждения, Тестирование C# и BSL, Документация
(
OneScriptDocumenter), Безопасность, Чек-лист готовности). В C#-шаблонах исправлены
using-и:OneScript.Executionвместонесуществующего
OneScript.Core.Execution, добавленScriptEngine.MachineдляIValue/ValueFactory. Намспейсы свереныс живым кодом (
OneScript.StandardLibrary/Json/GlobalJsonFunctions.cs,JSONWriterSettings.cs,StringOperations.cs).Изменений в исходном коде проекта нет — затронута только документация
в корне и в каталоге
docs/.Test plan
markdownlintпо всем 4 файлам — без предупрежденийsrc/,tests/,install/,docs/,.github/) фактически существуют в репозиторииBuild.csprojREADME.mdиREADME-EN.mdидентична (19 заголовковв одинаковом порядке)
using-и и неймспейсы в C#-шаблонах сверены с реальным кодомOneScript.StandardLibrary(компилируемость гарантированасверкой с рабочими классами)
Summary by CodeRabbit