Update doc feature support overview

Author: xoofx

doc/Programming Guide For CppAst.Net.md

@@ -192,15 +192,15 @@ From the above example, we can already see some advantages of CppAst.Net:
 2. It supports building Compilation directly from a string, which also facilitates the implementation of unit tests.
 
 ### 3.1 Easy to Start with Simple Configuration
-  CppAst.Net fundamentally relies on ClangSharp. Those who have experience with ClangSharp might be aware that the compilation and execution experience may not be very smooth. After adding the ClangSharp package from NuGet, attempting to run related examples and test codes might still prompt issues such as the absence of `libclang.dll/ligclang.so`, leading to a less than ideal experience. This situation can't be entirely blamed on ClangSharp, as it mainly stems from NuGet's limitations on the size of native binaries that a package can depend on. Since this issue might be encountered by many, let's first share a workaround to facilitate easier running of your own test codes:
+  CppAst.Net fundamentally relies on ClangSharp and its native libclang binaries. After adding the CppAst package from NuGet, projects should still select a runtime identifier so the correct native asset can be restored and loaded. A common project-file configuration is:
 ```xml
 <PropertyGroup>
     <!-- Workaround for issue https://github.com/microsoft/ClangSharp/issues/129 -->
     <RuntimeIdentifier Condition="'$(RuntimeIdentifier)' == '' AND '$(PackAsTool)' != 'true'">$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
 </PropertyGroup>
 ```
 
-For the official sample codes mentioned earlier, we can try to start from scratch and create a `C# .netcore 3.1` Console App, and step by step get it to run:
+For the official sample code mentioned earlier, we can start from scratch with a modern `.NET 8` console app and get it running step by step:
 
 #### 3.1.1 Creating a Project
 **Open Visual Studio and create a C# Console App (the environment used by the author is VS 2022):**
@@ -209,7 +209,7 @@ For the official sample codes mentioned earlier, we can try to start from scratc
 **Configure the project name:**
 ![3-2-guide2](cn/img/3-2-guide2.png)
 
-**Select the .net version (here we directly use .net core 3.1):**
+**Select the .NET version (the current package targets .NET 8):**
 ![3-3-guide](cn/img/3-3-guide.png)
 
 #### 3.1.2 Adding `CppAst.Net` Package via NuGet
@@ -229,26 +229,26 @@ For the official sample codes mentioned earlier, we can try to start from scratc
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
 
     <!-- Workaround for issue https://github.com/microsoft/ClangSharp/issues/129 -->
     <RuntimeIdentifier Condition="'$(RuntimeIdentifier)' == '' AND '$(PackAsTool)' != 'true'">$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="CppAst" Version="0.13.0" />
+    <PackageReference Include="CppAst" Version="LATEST_VERSION" />
   </ItemGroup>
 
 </Project>
 ```
-The `RuntimeIdentifier` entry is essential, as omitting it could lead to runtime errors due to missing libclang native dlls.
+Replace `LATEST_VERSION` with the current NuGet version. The `RuntimeIdentifier` entry is recommended so restore selects the native libclang asset for the current platform.
 
 #### 3.1.4 Adding Sample Code and Testing the App
 **Add test code in the Main() function of Program.cs:**
 ```cs
 static void Main(string[] args)
 {
-	// Parse a C++ files
+	// Parse C++ files
 	var compilation = CppParser.Parse(@"
 enum MyEnum { MyEnum_0, MyEnum_1 };
 void function0(int a, int b);
@@ -455,7 +455,7 @@ foo<int, int> foobar;
 
 ### 4.2 Support for `meta attribute`
 &emsp;&emsp;In this section, we added a specific document [attributes.md](https://github.com/xoofx/CppAst.NET/blob/main/doc/attributes.md) to the CppAst.Net code repository. Interested readers can consult it on their own. It mainly addresses the issue mentioned above about needing to configure certain exported items without wanting to separate the code items from the configuration information. Originally, CppAst.Net also had its own implementation of token attributes based on token parsing, but when used in projects, it encountered some issues frequently mentioned by the community:
-1. `ParseAttributes()` was time-consuming, leading to the introduction of the `ParseAttributes` parameter in later versions to control whether to parse `attributes`. However, in some cases, we rely on `attributes` to implement certain functionalities, which obviously was inconvenient.
+1. Token-based attribute parsing was time-consuming, so current versions keep that compatibility path opt-in through `CppParserOptions.ParseTokenAttributes`.
 
 2. There were flaws in parsing `meta attribute` - `[[]]`. `meta attribute` defined above `Function` and `Field` is semantically legal, but `cppast.net` could not properly support such `meta attribute` defined above objects (with some exceptions, like `namespace`, `class`, `enum`, where the attribute declaration itself cannot be placed above, as the compiler would directly report errors for such usages, it can only be placed after the related keywords, like `class [[deprecated]] Abc{};`).
 

doc/attributes.md

@@ -1,6 +1,6 @@
 ## 1. `cppast.net 0.12` Support for `attributes`
 The original support of `cppast.net` for various types of `attributes`, including the `meta attribute` of `c++17`, is restricted due to the limitation of `libclang` itself `Api`. We need to rely on token-level parsing to implement related functions. In the implementation of `cppast.net 0.12` and previous versions, we used parsing `token` to implement related functions. Even some `attributes` that `libclang` supports well, such as `dllexport`, `dllimport`, etc., `cppast.net` most of the time also uses token parsing. Although this approach is flexible and we can always try to parse the related `attributes` from the `token` level, it also brings some problems and restrictions, including:
-1. `ParseAttributes()` is extremely time-consuming, which led to the addition of the `ParseAttributes` parameter in later versions to control whether to parse `attributes`. However, in some cases, we need to rely on `attributes` to complete the related functions, which is obviously inconvenient.
+1. Token-based attribute parsing is comparatively expensive, which led to parser options that make fallback token parsing opt-in. In current CppAst versions, this compatibility path is controlled by `CppParserOptions.ParseTokenAttributes`.
 2. There are defects in the parsing of `meta attribute` - `[[]]`. For `meta attribute` defined above `Function` and `Field`, it is obviously legal at the semantic level, but `cppast.net` does not support this type of `meta attribute` defined above the object very well (there are some exceptions here, like `namespace`, `class`, `enum` these `attribute` declarations, the attribute definition itself cannot be at the top, the compiler will report an error directly for the related usage, it can only be after the related keywords, such as `class [[deprecated]] Abc{};`).
 3. Individual parameters of `meta attribute` use macros. Because our original implementation is based on `token` parsing, macros during compilation obviously cannot be correctly handled in this case.
 
@@ -17,7 +17,7 @@ Taking the code segment in the `cppast.net` test case as an example:
 #define EXPORT_API __attribute__((visibility(""default"")))
 #endif
 ```
-For `attributes` like `dllexport` and `visibility` that control interface visibility, we definitely use them more often, not only when `ParseAttributes` is turned on to make it work. We need to provide a high-performance solution for these basic system attributes, and the implementation should not be affected by the switch.
+For attributes like `dllexport` and `visibility` that control interface visibility, we need them more often than an opt-in token parser would allow. Current CppAst exposes supported system attributes through `Attributes` without requiring `ParseTokenAttributes`.
 
 ---
 ### 2.2 Injection of Additional Information by Export Tools and Other Tools

doc/cn/Programming Guide For CppAst.Net - cn.md

@@ -139,7 +139,7 @@ private static void PrintASTByCursor(CXCursor cursor, int level, List<string> sa
 ## 3. CppAst.Net - 新的天花板
 &emsp;&emsp;前面的铺垫比较长, 终于迎来我们的正主 [CppAst.Net](https://github.com/xoofx/CppAst.NET)了, 还是按照老规矩, **我们先来看一段 CppAst.Net 官网上的示例代码:**
 ```cs
-// Parse a C++ files
+// Parse C++ files
 var compilation = CppParser.Parse(@"
 enum MyEnum { MyEnum_0, MyEnum_1 };
 void function0(int a, int b);
@@ -180,15 +180,15 @@ typedef MyStruct* MyStructPtr
 2. 能够支持直接从字符串构建 Compilation, 这样也方便实现单元测试.
 
 ### 3.1 简单配置即可上手使用
-&emsp;&emsp;CppAst.Net底层是依赖ClangSharp的, 有过 ClangSharp 使用经念的同学可能都知道, 整个编译运行的体验可能并不太好, 从 NuGet 添加了 ClangSharp 包之后, 可能我们直接运行相关的示例和测试代码, 还是会提示 `libclang.dll/ligclang.so` 找不到之类的问题, 体验不会特别好, 这个其实也不能全怪 ClangSharp, 主要还是 NuGet 对包本身依赖的原生二进制的大小做了一些限制, 因为这个问题可能比较多人遇到, 我们先贴出一下相关的 Workaround, 方便大家更好的运行自己的测试代码:
+&emsp;&emsp;CppAst.Net 底层依赖 ClangSharp 和其 native libclang 二进制。从 NuGet 添加 CppAst 包之后，项目仍建议选择一个运行时标识符，以便还原并加载正确的 native 资产。常见的项目文件配置如下：
 ```xml
 <PropertyGroup>
     <!-- Workaround for issue https://github.com/microsoft/ClangSharp/issues/129 -->
     <RuntimeIdentifier Condition="'$(RuntimeIdentifier)' == '' AND '$(PackAsTool)' != 'true'">$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
 </PropertyGroup>
 ```
 
-对于前面说到的官方示例代码, 我们可以尝试从零开始建立一个` C# .netcore 3.1` 的Console App, 一步一步将其运行起来:
+对于前面说到的官方示例代码，我们可以尝试从零开始建立一个现代 `.NET 8` Console App，一步一步将其运行起来：
 
 #### 3.1.1 新建工程
 **打开 Visual Studio  建立一个C# Console App (笔者当前使用的环境是 VS 2022):**
@@ -217,27 +217,27 @@ typedef MyStruct* MyStructPtr
 
   <PropertyGroup>
     <OutputType>Exe</OutputType>
-    <TargetFramework>netcoreapp3.1</TargetFramework>
+    <TargetFramework>net8.0</TargetFramework>
 
     <!-- Workaround for issue https://github.com/microsoft/ClangSharp/issues/129 -->
     <RuntimeIdentifier Condition="'$(RuntimeIdentifier)' == '' AND '$(PackAsTool)' != 'true'">$(NETCoreSdkRuntimeIdentifier)</RuntimeIdentifier>
   </PropertyGroup>
 
   <ItemGroup>
-    <PackageReference Include="CppAst" Version="0.13.0" />
+    <PackageReference Include="CppAst" Version="LATEST_VERSION" />
   </ItemGroup>
 
 </Project>
 
 ```
-也就是上面的 `RuntimeIdentifier` 项, 这个是必须的, 不然容易出现运行时找不到 libclang 的 native dll的报错.
+请将 `LATEST_VERSION` 替换为当前 NuGet 版本。上面的 `RuntimeIdentifier` 项建议保留，这样还原时会选择当前平台对应的 native libclang 资产。
 
 #### 3.1.4 添加示例代码后测试运行对应的App
 **在Program.cs的Main()函数中添加测试代码:**
 ```cs
 static void Main(string[] args)
 {
-	// Parse a C++ files
+	// Parse C++ files
 	var compilation = CppParser.Parse(@"
 enum MyEnum { MyEnum_0, MyEnum_1 };
 void function0(int a, int b);
@@ -371,7 +371,7 @@ foo<int, int> foobar;
 
 ### 4.2 `meta attribute` 支持
 &emsp;&emsp;这一部分我们在CppAst.Net的代码仓库里添加了一个具体的文档 [attributes.md](https://github.com/xoofx/CppAst.NET/blob/main/doc/attributes.md), 感兴趣的读者可以自行查阅, 主要是用来解决上面提到的需要对某些导出项进行配置, 但又不希望代码项和配置信息分离的问题的, 原来 CppAst.Net 也有一版自己的基于再次 token parse 的 token attributes实现, 不过实际用于项目存在一些社区中比较多反馈的问题:
-1. `ParseAttributes()` 耗时巨大, 所以导致了后来的版本中加入了`ParseAttributes` 参数来控制是否解析 `attributes`, 但某些场合, 我们需要依赖 `attributes` 才能完成相关的功能实现. 这显然带来了不便.
+1. 基于 token 的 attribute 解析成本较高，因此当前版本将这条兼容路径改为通过 `CppParserOptions.ParseTokenAttributes` 按需开启。
 
 2. 对 `meta attribute` - `[[]]` 的解析存在缺陷, 像 `Function` 和 `Field` 上方定义的 `meta attribute`, 在语义层面, 显然是合法的, 但 `cppast.net` 并不能很好的支持这种在对象上方定义的`meta attribute` (这里存在一些例外情况, 像 `namespace`, `class`, `enum` 这些的 `attribute` 声明, attribute定义本身就不能位于上方, 相关的用法编译器会直接报错, 只能在相关的关键字后面, 如 `class [[deprecated]] Abc{};` 这种 ).
 

doc/cn/attributes-cn.md

@@ -2,7 +2,7 @@
 
 ## 1. `cppast.net 0.12` 对 `attributes` 支持情况
 `cppast.net` 原有的对各类 `attribute` 的支持, 包括 `c++17` 的 `meta attribute` 的支持, 由于 `libclang` 本身 `Api` 的限制, 我们需要借助 token 层级的解析, 才能够完成相关的功能实现. 在 `cppast.net 0.12` 版本及以前的实现中, 我们都使用了解析 `token` 的方式来实现相关的功能, 甚至连一些 `libclang` 中能够很好的支持的 `attribute`, 如 `dllexport`, `dllimport` 等, `cppast.net` 大部分时候也是使用 token 解析来实现的. 这样做虽然灵活, 我们始终能够从 `token` 层级尝试解析相关的 `attribute`, 但也带来了一些问题和限制, 社区中比较多反馈的问题:
-1. `ParseAttributes()` 耗时巨大, 所以导致了后来的版本中加入了`ParseAttributes` 参数来控制是否解析 `attributes`, 但某些场合, 我们需要依赖 `attributes` 才能完成相关的功能实现. 这显然带来了不便.
+1. 基于 token 的 attribute 解析成本较高，因此后续版本将 fallback token 解析改为按需开启。在当前 CppAst 版本中，这条兼容路径由 `CppParserOptions.ParseTokenAttributes` 控制。
 2. 对 `meta attribute` - `[[]]` 的解析存在缺陷, 像 `Function` 和 `Field` 上方定义的 `meta attribute`, 在语义层面, 显然是合法的, 但 `cppast.net` 并不能很好的支持这种在对象上方定义的`meta attribute` (这里存在一些例外情况, 像 `namespace`, `class`, `enum` 这些的 `attribute` 声明, attribute定义本身就不能位于上方, 相关的用法编译器会直接报错, 只能在相关的关键字后面, 如 `class [[deprecated]] Abc{};` 这种 ). 
 3. `meta attribute` 个别参数使用宏的情况. 因为我们原有的实现是基于 `token` 解析来实现的, 编译期的宏显然不能很好的在这种情况下被正确处理.
 
@@ -19,7 +19,7 @@
 #define EXPORT_API __attribute__((visibility(""default"")))
 #endif
 ```
- 像 `dllexport` 和 `visibility` 这种控制接口可见性的 `attribute`, 我们肯定是比较常用的, 而不仅仅是只有在打开 `ParseAttributes` 的时候才让它能够工作, 我们需要为这些基础的系统属性提供高性能的解决方案, 而且相关的实现应该是不受开关影响的.
+ 像 `dllexport` 和 `visibility` 这种控制接口可见性的 `attribute` 非常常用，不应该依赖可选的 token 解析开关。当前 CppAst 会通过 `Attributes` 暴露支持的系统 attribute，而不需要开启 `ParseTokenAttributes`。
 
 ---
 ### 2.2 导出工具等工具额外的信息注入