add directives comment

src/completion/directives.rs

@@ -5,6 +5,7 @@ use tower_lsp::lsp_types::*;
 /// date: 2024.12.13
 
 pub const VLOG_DIRECTIVES: &[(&str, &str, &str)] = &[
+    // 1800-2009 22.13 `__FILE__ and `__LINE__ 
     (
         "__FILE__",
         "`__FILE__",
@@ -37,43 +38,7 @@ module test;
 endmodule
 ```
 "#),
-    (
+    // 19.1 `celldefine and `endcelldefine
-        "begin_keywords",
-        "`begin_keywords\n$1\n`end_keywords ",
-r#"`begin_keywords` 和 `end_keywords` 是用于指定 Verilog 语言版本的编译指令。它们允许设计者在同一个文件中使用不同版本的 Verilog 语法，从而实现兼容性或逐步迁移到新版本。
-
-`begin_keywords` 支持以下 Verilog 版本：
-
-- `1364-1995`：Verilog-1995 标准。
-- `1364-2001`：Verilog-2001 标准。
-- `1364-2005`：Verilog-2005 标准。
-- `1800-2009`：SystemVerilog-2009 标准。
-- `1800-2012`：SystemVerilog-2012 标准。
-
-```verilog
-// 使用 begin_keywords 和 end_keywords 指定 Verilog 版本
-`begin_keywords "1364-2001" // 指定 Verilog-2001 语法
-
-module my_module;
-    reg [7:0] data;
-    initial begin
-        data = 8'hFF; // 使用 Verilog-2001 的语法
-        $display("Verilog-2001 语法: data = %h", data);
-    end
-endmodule
-
-`end_keywords // 结束 Verilog-2001 语法
-
-// 恢复默认的 Verilog 语法
-module another_module;
-    reg [7:0] data;
-    initial begin
-        data = 8'hAA; // 使用默认的 Verilog 语法
-        $display("默认语法: data = %h", data);
-    end
-endmodule
-```
-"#),
     (
         "celldefine",
         "`celldefine\n$1\n`endcelldefine",
@@ -123,11 +88,18 @@ endmodule
 - 编译器可以将 `celldefine` 模块视为标准单元库的一部分，从而进行更高效的编译优化。例如，编译器可以提前处理这些模块的逻辑，减少仿真时的计算开销。
 - 在大型设计中，标准单元库模块可能会被多次实例化。使用 celldefine 可以避免重复编译相同的模块，从而减少编译时间和内存占用。
 "#),
+    (
+        "endcelldefine",
+        "`endcelldefine",
+        "结束单元格定义"
+    ),
+    // 19.2 `default_nettype
     (
         "default_nettype",
         "`default_nettype $1",
         "设置默认的网络类型"
     ),
+    // 19.3 `define and `undef
     (
         "define",
         "`define $1 $2",
@@ -166,30 +138,17 @@ endmodule
 ```
 "#),
     (
-        "else",
+        "undef",
-        "`else",
+        "`undef $1",
-        "条件编译的 else 分支"
+        "取消定义一个宏"
     ),
+    // 1800-2009 22.5 `define, `undef and `undefineall 
     (
-        "elsif",
+        "undefineall",
-        "`elsif $1",
+        "`undefineall",
-        "条件编译的 elsif 分支"
+        "取消定义所有宏"
-    ),
-    (
-        "end_keywords",
-        "`end_keywords",
-        "结束关键字版本指定"
-    ),
-    (
-        "endcelldefine",
-        "`endcelldefine",
-        "结束单元格定义"
-    ),
-    (
-        "endif",
-        "`endif",
-        "结束条件编译"
     ),
+    // 19.4 `ifdef, `else, `elsif, `endif, `ifndef
     (
         "ifdef",
         "`ifdef $1\n\t//ifdef\n\t$2\n`else\n//else\n\t$3\n`endif",
@@ -235,16 +194,53 @@ endmodule
 
 "#
     ),
+    (
+        "else",
+        "`else",
+        "条件编译的 else 分支"
+    ),
+    (
+        "elsif",
+        "`elsif $1",
+        "条件编译的 elsif 分支"
+    ),
+    (
+        "endif",
+        "`endif",
+        "结束条件编译"
+    ),
     (
         "ifndef",
         "`ifndef $1",
         "如果未定义宏，则编译代码"
     ),
+    // 19.5 `include
     (
         "include",
         "`include $1",
         "包含一个外部文件"
     ),
+    // 19.6 `resetall
+    (
+        "resetall",
+        "`resetall",
+    // resetall 也常用于开始
+    // 1834-2005中指出，建议的用法是将 `resetall 放在每个源文本文件的开头，后面紧跟着文件中所需的指令。
+    // 通常可用于源文本开头，避免该文件受到其他文件代码的影响。或放置在末尾，避免编译器设置的进一步传递
+r#"`resetall` 用于重置所有编译器设置为默认值。它通常用于在模块或文件的末尾清除所有编译器设置，以确保后续代码不受之前设置的影响。
+
+```verilog
+`timescale 1ns/1ps // 设置时间单位和精度
+
+module test;
+    // 一些 verilog 代码
+endmodule
+
+`resetall // 重置所有编译器设置，上文的 timescale 设置自此开始无效
+```
+"#
+    ),
+    // 19.7 `line
     (
         "line",
         "`line $1 $2 $3",
@@ -269,55 +265,14 @@ endmodule
 ```
 "#
     ),
-    (
+    // 19.8 `timescale
-        "unconnected_drive",
-        "`unconnected_drive ${1:pull1}\n$2\n`nounconnected_drive\n",
-r#"`nounconnected_drive` 和 `unconnected_drive` 是配合使用的编译指令，用于控制未连接端口的驱动行为。它们通常成对出现，分别用于禁用和启用未连接端口的驱动处理。
-### 语法
-```verilog
-`unconnected_drive (pull1 | pull0) // 启用未连接端口的驱动，若为 pull1，则默认驱动为高电平，若为 pull0，则默认为低电平
-    // 你的 verilog 代码
-`nounconnected_drive               // 禁用未连接端口的驱动
-```
-
-"#
-    ),
-    (
-        "nounconnected_drive",
-        "`nounconnected_drive",
-r#"`nounconnected_drive` 和 `unconnected_drive` 是配合使用的编译指令，用于控制未连接端口的驱动行为。它们通常成对出现，分别用于禁用和启用未连接端口的驱动处理。
-### 语法
-```verilog
-`unconnected_drive (pull1 | pull0) // 启用未连接端口的驱动，若为 pull1，则默认驱动为高电平，若为 pull0，则默认为低电平
-    // 你的 verilog 代码
-`nounconnected_drive               // 禁用未连接端口的驱动
-```
-"#
-    ),
-    (
-        "pragma",
-        "`pragma $1",
-        "编译指示，用于传递编译器指令"
-    ),
-    (
-        "resetall",
-        "`resetall",
-r#"`resetall` 用于重置所有编译器设置为默认值。它通常用于在模块或文件的末尾清除所有编译器设置，以确保后续代码不受之前设置的影响。
-
-```verilog
-`timescale 1ns/1ps // 设置时间单位和精度
-
-module test;
-    // 一些 verilog 代码
-endmodule
-
-`resetall // 重置所有编译器设置，上文的 timescale 设置自此开始无效
-```
-"#
-    ),
     (
         "timescale",
         "`timescale ${1:1ns}/${2:1ps}",
+    // 原文是The time_precision argument shall be at least as precise as the time_unit argument; it cannot specify a longer unit of time than time_unit.
+    // 也即是，仿真时间单位必须大于等于时间精度
+    // `timescale 1ns/1ns不会报错，但是`timescale 1ps/1ns会报错
+    // [Synth 8-522] parsing error: error in timescale or timeprecision statement. <timeprecision> must be at least as precise as <timeunit>
 r#"设置时间单位和精度，设置时间单位和精度，格式为 <code> `timescale </code> 仿真时间单位/时间精度，<code>仿真时间单位</code> 必须大于 <code>时间精度</code>，例如
 ```verilog
 `timescale 1ns/1ps
@@ -334,16 +289,100 @@ endmodule
 
 在编译过程中，`timescale` 指令影响这一编译器指令后面所有模块中的时延值，直至遇到另一个 `timescale` 指令 `resetall` 指令。
 "#),
+    // 19.9 `unconnected_drive and `nounconnected_drive
     (
-        "undef",
+        "unconnected_drive",
-        "`undef $1",
+        "`unconnected_drive ${1:pull1}\n$2\n`nounconnected_drive\n",
-        "取消定义一个宏"
+r#"`nounconnected_drive` 和 `unconnected_drive` 是配合使用的编译指令，用于控制未连接端口的驱动行为。它们通常成对出现，分别用于禁用和启用未连接端口的驱动处理。
+### 语法
+```verilog
+`unconnected_drive (pull1 | pull0) // 启用未连接端口的驱动，若为 pull1，则默认驱动为高电平，若为 pull0，则默认为低电平
+    // 你的 verilog 代码
+`nounconnected_drive               // 禁用未连接端口的驱动
+```
+
+### 示例
+```verilog
+// 使用 `line 指令指定行号和文件名
+`unconnected_drive pull1
+module my_and(y, a, b);
+    output y;
+    input a, b;
+    assign y = a & b;
+endmodule
+
+module test(y,b);
+    output y;
+    input b;
+    my_and ul(y, ,b);
+endmodule
+`nounconnected_drive
+```
+"#
     ),
     (
-        "undefineall",
+        "nounconnected_drive",
-        "`undefineall",
+        "`nounconnected_drive",
-        "取消定义所有宏"
+r#"`nounconnected_drive` 和 `unconnected_drive` 是配合使用的编译指令，用于控制未连接端口的驱动行为。它们通常成对出现，分别用于禁用和启用未连接端口的驱动处理。
+### 语法
+```verilog
+`unconnected_drive (pull1 | pull0) // 启用未连接端口的驱动，若为 pull1，则默认驱动为高电平，若为 pull0，则默认为低电平
+    // 你的 verilog 代码
+`nounconnected_drive               // 禁用未连接端口的驱动
+```
+"#
     ),
+    // 19.10 `pragma
+    (
+        "pragma",
+        "`pragma $1",
+        "编译指示，用于传递编译器指令"
+    ),
+    // 19.11 `begin_keywords, `end_keywords
+    (
+        "begin_keywords",
+        "`begin_keywords\n$1\n`end_keywords ",
+    // begin_keywords并不是指定Verilog的编译版本，而是指定使用的Verilog关键字版本
+r#"`begin_keywords` 和 `end_keywords` 是用于指定 Verilog 语言版本的编译指令。它们允许设计者在同一个文件中使用不同版本的 Verilog 语法，从而实现兼容性或逐步迁移到新版本。
+
+`begin_keywords` 支持以下 Verilog 版本：
+
+- `1364-1995`：Verilog-1995 标准。
+- `1364-2001`：Verilog-2001 标准。
+- `1364-2005`：Verilog-2005 标准。
+- `1800-2009`：SystemVerilog-2009 标准。
+- `1800-2012`：SystemVerilog-2012 标准。
+
+```verilog
+// 使用 begin_keywords 和 end_keywords 指定 Verilog 版本
+`begin_keywords "1364-2001" // 指定 Verilog-2001 语法
+
+module my_module;
+reg [7:0] data;
+initial begin
+    data = 8'hFF; // 使用 Verilog-2001 的语法
+    $display("Verilog-2001 语法: data = %h", data);
+end
+endmodule
+
+`end_keywords // 结束 Verilog-2001 语法
+
+// 恢复默认的 Verilog 语法
+module another_module;
+reg [7:0] data;
+initial begin
+    data = 8'hAA; // 使用默认的 Verilog 语法
+    $display("默认语法: data = %h", data);
+end
+endmodule
+```
+"#),
+    (
+        "end_keywords",
+        "`end_keywords",
+        "结束关键字版本指定"
+    ),
+    // Annex D Compiler directives
     (
         "default_decay_time",
         "`default_decay_time $1",