docs(prompt): 转化 prompt 注释为文档化注释

plugins/lib/ui/prompt.tin

@@ -12,102 +12,104 @@ PaoTin++ © 2020~2023 的所有版权均由担子炮(dzp <danzipao@gmail.com>)
     {AUTHOR}    {担子炮}
 };
 
-/*
-prompt 插件把整个屏幕划分为七个区域，从上到下依次为：
-
-Top line1
-Top line2
-...
-Top lineN
------------ TopSepBar --------------
-（游戏区）
------------ MidSepBar --------------
-Bot line1
-Bot line2
-...
-Bot lineN
------------ BotSepBar --------------
-<提示符>:（输入区）
-
-输入区前面的提示符部分可以用 API prompt.Change 来修改。
-
-除输入区和游戏区之外，剩下五个区域都可以定制，用来显示信息内容（以下称为字段）。
-每一行都可以有多个字段。字段在视觉上由两部分组成，字段标签和字段内容。
-其显示样式分别可以控制，并受到几个 prompt 特性的影响，下面会分别予以介绍。
-
-字段的编排是高度可定制的，每个字段的标签、内容、颜色、显示风格、行为属性，
-都可以通过自己修改 #list prompt-fields 来修改。下面是对 #list prompt-fields
-的格式说明，但不建议直接在此处修改变量，请通过 etc/ui-settings.tin 来修改。
-prompt 模块在启动时会自动加载该文件。
-
-#list prompt-fields 是一个列表，其中中每个元素是一个 tt++ table，代表一个字段。
-tt++ table 由一组选项和与之对应的选项值来组成，用来说明想要定制的字段的选项。
-
-下面是所有可供设置的字段选项：
-
-1. place 枚举值 可选项: {Top|TopSepBar|MidSepBar|Bot|BotSepBar}
-  希望将字段显示在屏幕上的什么位置。
-  其中 {Top} 和 {Bot} 支持多行，其它三个只有一行。
-  默认为 BotSepBar。
-
-2. line 自然数
-   只有 place={Top|Bot} 才支持 line，代表第几行，最上面是第一行。
-   默认为 1。
-
-3. order 自然数
-   在同一行中的次序，默认按照在 list 中出现的顺序来排序。
-
-4. label 中英文字符串
-   字段标签，每个字段都可以有一个标签，显示在内容前面。
-   默认为空白。
-
-5. color tintin 格式的颜色代码，例如 <ddd>
-   字段值的颜色，通过该选项可以为字段值指定一个与配色主题不一样的颜色。
-   一般来说只有极个别选项才需要特别的颜色，没必要为每个选项都指定颜色，
-   因为那样的话你还不如去设置配色主题，参见下面配色主题的设置。
-   默认为空白，代表采用配色主题。
-
-6. name 英文字符串 不能为空
-   字段名称，必须唯一，不能重复。
-
-7. width 整数
-   字段内容的宽度，如果字段内容长度变化较大，可以设置一个固定宽度，以免晃动。
-   默认为 0，表示按照内容长度自动适配。
-
-8. visibility 枚举值 {HideEmpty|HideCool|HideZero|HideLabel|Always}
-   含义如下：
-    * HideEmpty 如果字段内容为空则不予显示。
-    * HideCool  如果内容已陈旧则不予显示。请参考 cooldown 选项。
-    * HideZero  如果倒计时归零则不予显示。请参考 countdown 选项。
-    * HideLabel 仅显示字段内容，不显示字段标签。
-    * Always    总是显示该字段的标签和内容。
-   所有的 Hide* 选项自动拥有 HideEmpty 语义。
-   默认为 HideEmpty。
-
-9. cooldown 非负整数
-   该字段的有效时间。超过有效时间没有更新的字段将在视觉上予以弱化显示，以提醒
-   用户。也就是说，如果 cooldown 不为 0，则该字段被更新时其标签将会以颜色主题
-   中 HotLabel 所指定的风格显示（意指新鲜的内容），之后持续若干秒后，转为由
-   CoolLabel 所指定的风格显示（意指陈旧的内容）。
-   持续时间由 cooldown 字段的值来决定，单位为秒。
-   陈旧的内容遇到 visibility=HideCool 时则不予显示。
-   如果 cooldown 为 0，则不会以 CoolLabel 风格显示。
-   默认值为 0。
-
-10. countdown 枚举值 {Auto|Clock|Seconds}
-   倒计时类型的字段。其内容为一个非负整数，代表需要倒计时的秒数，或者也可以夹杂
-   于文字内容当中，此时文字内容中所有形如 (%d) 的内容将会被替换成倒计时显示。
-   本插件会自动为该字段更新其内容，使得用户能够看到倒计时的效果。
-   倒计时有两种显示样式，本选项设置为 Clock 时，显示为时钟样式（N天HH:MM:SS），
-   设置为 Seconds 时，显示为读秒样式（N秒）。设置为 Auto 时则根据剩余时间长短，
-   自动切换两种显示效果。
-   倒计时类型的字段，如果同时设置了 visibility=HideZero，那么倒计时归零后会自动
-   隐藏该字段。
-   在倒计时存续期间，该字段的 cooldown 属性将会被抑制，直到倒计时归零后才起作用。
-   这条规则确保倒计时字段即使设置了 visibility=HideCool，也至少会完成倒计时，而
-   倒计时结束后，如果 cooldown 时间比倒计时时间还要长，则还会继续显示一段时间之
-   后才会被隐藏。
-*/
+///=== {
+///// prompt 是 PaoTin++ 中非常重要的 UI 插件，现行 UI 的主要元素都是由 prompt 来支撑的。
+/////
+///// prompt 插件把整个 TinTin++ 屏幕划分为七个区域，从上到下依次为：
+///// 
+///// Top line1
+///// Top line2
+///// ...
+///// Top lineN
+///// ----------- TopSepBar --------------
+///// （游戏区）
+///// ----------- MidSepBar --------------
+///// Bot line1
+///// Bot line2
+///// ...
+///// Bot lineN
+///// ----------- BotSepBar --------------
+///// <提示符>:（输入区）
+///// 
+///// 输入区前面的提示符部分可以用 API prompt.Change 来修改。
+///// 
+///// 除输入区和游戏区之外，剩下五个区域都可以定制，用来显示信息内容（以下称为字段）。
+///// 每一行都可以有多个字段。字段在视觉上由两部分组成，字段标签和字段内容。
+///// 其显示样式分别可以控制，并受到几个 prompt 特性的影响，下面会分别予以介绍。
+///// 
+///// 字段的编排是高度可定制的，每个字段的标签、内容、颜色、显示风格、行为属性，
+///// 都可以通过自己修改 #list prompt-fields 来修改。下面是对 #list prompt-fields
+///// 的格式说明，但不建议直接在此处修改变量，请通过 var/etc/ui-settings.tin 来修改。
+///// prompt 模块在启动时会自动加载该文件。
+///// 
+///// #list prompt-fields 是一个列表，其中中每个元素是一个 tt++ table，代表一个字段。
+///// tt++ table 由一组选项和与之对应的选项值来组成，用来说明想要定制的字段的选项。
+///// 
+///// 下面是所有可供设置的字段选项：
+///// 
+///// 1. place 枚举值 可选项: {Top|TopSepBar|MidSepBar|Bot|BotSepBar}
+/////    希望将字段显示在屏幕上的什么位置。
+/////    其中 {Top} 和 {Bot} 支持多行，其它三个只有一行。
+/////    默认为 BotSepBar。
+///// 
+///// 2. line 自然数
+/////    只有 place={Top|Bot} 才支持 line，代表第几行，最上面是第一行。
+/////    默认为 1。
+///// 
+///// 3. order 自然数
+/////    在同一行中的次序，默认按照在 list 中出现的顺序来排序。
+///// 
+///// 4. label 中英文字符串
+/////    字段标签，每个字段都可以有一个标签，显示在内容前面。
+/////    默认为空白。
+///// 
+///// 5. color tintin 格式的颜色代码，例如 <ddd>
+/////    字段值的颜色，通过该选项可以为字段值指定一个与配色主题不一样的颜色。
+/////    一般来说只有极个别选项才需要特别的颜色，没必要为每个选项都指定颜色，
+/////    因为那样的话你还不如去设置配色主题，参见下面配色主题的设置。
+/////    默认为空白，代表采用配色主题。
+///// 
+///// 6. name 英文字符串 不能为空
+/////    字段名称，必须唯一，不能重复。
+///// 
+///// 7. width 整数
+/////    字段内容的宽度，如果字段内容长度变化较大，可以设置一个固定宽度，以免晃动。
+/////    默认为 0，表示按照内容长度自动适配。
+///// 
+///// 8. visibility 枚举值 {HideEmpty|HideCool|HideZero|HideLabel|Always}
+/////    含义如下：
+/////     * HideEmpty 如果字段内容为空则不予显示。
+/////     * HideCool  如果内容已陈旧则不予显示。请参考 cooldown 选项。
+/////     * HideZero  如果倒计时归零则不予显示。请参考 countdown 选项。
+/////     * HideLabel 仅显示字段内容，不显示字段标签。
+/////     * Always    总是显示该字段的标签和内容。
+/////    所有的 Hide* 选项自动拥有 HideEmpty 语义。
+/////    默认为 HideEmpty。
+///// 
+///// 9. cooldown 非负整数
+/////    该字段的有效时间。超过有效时间没有更新的字段将在视觉上予以弱化显示，以提醒
+/////    用户。也就是说，如果 cooldown 不为 0，则该字段被更新时其标签将会以颜色主题
+/////    中 HotLabel 所指定的风格显示（意指新鲜的内容），之后持续若干秒后，转为由
+/////    CoolLabel 所指定的风格显示（意指陈旧的内容）。
+/////    持续时间由 cooldown 字段的值来决定，单位为秒。
+/////    陈旧的内容遇到 visibility=HideCool 时则不予显示。
+/////    如果 cooldown 为 0，则不会以 CoolLabel 风格显示。
+/////    默认值为 0。
+///// 
+///// 10. countdown 枚举值 {Auto|Clock|Seconds}
+/////    倒计时类型的字段。其内容为一个非负整数，代表需要倒计时的秒数，或者也可以夹杂
+/////    于文字内容当中，此时文字内容中所有形如 (%d) 的内容将会被替换成倒计时显示。
+/////    本插件会自动为该字段更新其内容，使得用户能够看到倒计时的效果。
+/////    倒计时有两种显示样式，本选项设置为 Clock 时，显示为时钟样式（N天HH:MM:SS），
+/////    设置为 Seconds 时，显示为读秒样式（N秒）。设置为 Auto 时则根据剩余时间长短，
+/////    自动切换两种显示效果。
+/////    倒计时类型的字段，如果同时设置了 visibility=HideZero，那么倒计时归零后会自动
+/////    隐藏该字段。
+/////    在倒计时存续期间，该字段的 cooldown 属性将会被抑制，直到倒计时归零后才起作用。
+/////    这条规则确保倒计时字段即使设置了 visibility=HideCool，也至少会完成倒计时，而
+/////    倒计时结束后，如果 cooldown 时间比倒计时时间还要长，则还会继续显示一段时间之
+/////    后才会被隐藏。
+// };
 
 VAR {信息栏的字段列表} prompt-fields {};