docs: актуализация документации проекта (.NET 8, корректные пути, дописанные разделы) - #1669
Conversation
Sorry, something went wrong.
…ктуру кода - 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.
📝 Walkthrough
WalkthroughDocumentation 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. ❤️ Share Review rate limit: 7/8 reviews remaining, refill in 7 minutes and 30 seconds.Comment @coderabbitai help to get the list of available commands and usage tips. |
Sorry, something went wrong.
There was a problem hiding this comment.
docs/contexts.md (1)🤖 Prompt for all review comments with AI agentsdocs/developer_docs.md (1)3-6: Minor doc polish: make the “См. также” link text match the href target.
In docs/contexts.md you have:
- link text: docs/developer_docs.md
- href: developer_docs.md (relative to the current docs/ folder)
The href works, but the visible text is inconsistent. Consider changing either the text to developer_docs.md or the href to ../docs/developer_docs.md (though the latter is unnecessary from within docs/).
🛠️ Suggested diff🤖 Prompt for AI Agents-См. также [`docs/developer_docs.md`](developer_docs.md) — карта компонентов и «куда лезть» при доработках. +См. также [`developer_docs.md`](developer_docs.md) — карта компонентов и «куда лезть» при доработках.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.README.md (2)5-10: Minor doc polish: make the “См. также” link text match the href target.
Similar to docs/contexts.md, this file shows link text docs/contexts.md but the href is contexts.md (relative within docs/). The link likely resolves, but the visible text is misleading.
🛠️ Suggested diff🤖 Prompt for AI Agents-- [`docs/contexts.md`](contexts.md) — практическое руководство по добавлению BSL-контекстов и глобальных методов; +- [`contexts.md`](contexts.md) — практическое руководство по добавлению BSL-контекстов и глобальных методов;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-EN.md (2)122-145: Clarify that BSL runner paths assume Debug output (UX correctness).
The wrapper commands hardcode .../bin/Debug/net8.0/.... The doc later says to run dotnet build src/oscript/oscript.csproj before acceptance tests—by default that builds Debug, so it works—but it will silently break if someone earlier builds with Release / LinuxDebug.
Add a short note that these paths correspond to the default Debug configuration, or point users to adjust the path to match their Configuration.
🛠️ Suggested diffBefore 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.md around 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.🤖 Prompt for AI Agents</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 ## -# Тестирование +# Тестирование # -# Документация для разработчиков +# Документация для разработчиков #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.122-145: Clarify BSL runner paths assume Debug output (UX correctness).
The BSL acceptance test wrapper commands reference .../bin/Debug/net8.0/oscript(.exe). That matches dotnet build default configuration, but it won’t match if the user builds oscript with Release or another Configuration.
Add a short note to adjust the wrapper path (or build oscript in Debug) based on the Configuration used.
🤖 Prompt for AI AgentsVerify 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 AgentsVerify 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.
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
📥 CommitsReviewing files that changed from the base of the PR and between 49387e2 and f8af9ef.
📒 Files selected for processing (4)- README-EN.md
- README.md
- docs/contexts.md
- docs/developer_docs.md
Sorry, something went wrong.
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
docs/, .github/) фактически существуют в репозитории
Build.csproj
в одинаковом порядке)
OneScript.StandardLibrary (компилируемость гарантирована
сверкой с рабочими классами)
Summary by CodeRabbit