Improve Lua docs for enums and fields. (beyond-all-reason#1978)

* Update `@field` annotations in LuaConstGL

* Use lua-doc-extractor 2

* Update `@field` annotations in LuaConstCMD

* Update `@field` annotations in LuaConstCOB

* Update `@field` annotations in LuaConstCMDTYPE

* Remove leading `@section` on LuaConstGL

* Upload generated lua library during site-build

For debugging

* Remove ignore dirs from doc .luarc.json

* site README: Delete old generated library in example

* Improve lua doc enum template

* Remove hr from various doc templates

* Update lua-doc-extractor to v3

Author: rhys-vdw

.github/workflows/generate-lua-library.yml

@@ -26,7 +26,7 @@ jobs:
       - name: Generate Lua library
         working-directory: recoil
         run: |
-          npm install -g lua-doc-extractor@1
+          npm install -g lua-doc-extractor@3
           lua-doc-extractor rts/Lua/*.cpp \
             --dest rts/Lua/library/generated \
             --repo https://github.com/${{ github.repository }}/blob/${{ github.sha }}

.github/workflows/publish-site.yml

@@ -24,10 +24,16 @@ jobs:
       # NOTE: This step is duplicated in `generate-lua-library.yml`
       - name: Generate Lua library
         run: |
-          npm install -g lua-doc-extractor@1
+          npm install -g lua-doc-extractor@3
           lua-doc-extractor rts/Lua/*.cpp \
             --dest rts/Lua/library/generated \
             --repo https://github.com/${{ github.repository }}/blob/${{ github.sha }}
+      # Upload the Lua library artifact for debugging.
+      - name: Upload Lua Library artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: ${{github.run_id}}-library
+          path: rts/Lua/library/
       - name: Install emmylua_doc_cli
         run: |
           cargo install emmylua_doc_cli

doc/emmlua-doc-cli-template/lua_enum_template.tl

@@ -15,10 +15,14 @@ permalink: lua-api/types/{{ type_name }}
 {{ description }}
 {% endif %}
 
-```cpp
-enum {{ type_name }} {
-    {% for field in fields -%}
-        {{ field.name }} = {{ field.value }}, {{ field.description }}
-    {% endfor %}
-}
+{% for field in fields -%}
+
+### {{ field.name }}
+
+```lua
+{{ type_name }}.{{ field.name }} = {{ field.value }}
 ```
+
+{{ field.description }}
+
+{% endfor %}

doc/emmlua-doc-cli-template/lua_global_template.tl

@@ -10,13 +10,13 @@ permalink: lua-api/globals/{{ global_name }}
 {% if description %}
 {{ description }}
 {% endif %}
----
+
 {% if methods %}
 ## methods
----
+
 {% for method in methods %}
 ### {{ method.name }}
----
+
 {{ method.display }}
 
 {% if method.description %}
@@ -27,10 +27,10 @@ permalink: lua-api/globals/{{ global_name }}
 
 {% if fields %}
 ## fields
----
+
 {% for field in fields %}
 ### {{ field.name }}
----
+
 {{ field.display }}
 
 {% if field.description %}

doc/emmlua-doc-cli-template/lua_global_template_simple.tl

@@ -7,7 +7,6 @@ permalink: lua-api/globals/{{ global_name }}
 
 # global {{ global_name }}
 
----
 {% if display %}
 {{ display }}
 {% endif %}

doc/emmlua-doc-cli-template/lua_module_template.tl

@@ -10,13 +10,13 @@ permalink: lua-api/modules/{{ module_name }}
 {% if description %}
 {{ description }}
 {% endif %}
----
+
 {% if methods %}
 ## methods
----
+
 {% for method in methods %}
 ### {{ method.name }}
----
+
 {{ method.display }}
 
 {% if method.description %}
@@ -27,10 +27,10 @@ permalink: lua-api/modules/{{ module_name }}
 
 {% if fields %}
 ## fields
----
+
 {% for field in fields %}
 ### {{ field.name }}
----
+
 {{ field.display }}
 
 {% if field.description %}

doc/emmlua-doc-cli-template/lua_type_template.tl

@@ -17,13 +17,13 @@ permalink: lua-api/types/{{ type_name }}
 {% if description %}
 {{ description }}
 {% endif %}
----
+
 {% if methods %}
 ## methods
----
+
 {% for method in methods %}
 ### {{ method.name }}
----
+
 {{ method.display }}
 
 {% if method.description %}
@@ -34,10 +34,10 @@ permalink: lua-api/types/{{ type_name }}
 
 {% if fields %}
 ## fields
----
+
 {% for field in fields %}
 ### {{ field.name }}
----
+
 {{ field.display }}
 
 {% if field.description %}

doc/site/README.md

@@ -20,6 +20,7 @@ Navigate to http://localhost:4000/spring
 Have [emmylua_doc_cli](https://github.com/CppCXY/emmylua-analyzer-rust/tree/main/crates/emmylua_doc_cli) and [lua-doc-extractor](https://github.com/rhys-vdw/lua-doc-extractor) installed and available in `$PATH`.
 
 ```bash
+rm -rf rts/Lua/library/generated &&
 lua-doc-extractor rts/Lua/*.cpp --dest rts/Lua/library/generated &&
   emmylua_doc_cli \
     -i rts/Lua/library/ \

rts/Lua/LuaConstCMD.cpp

@@ -9,149 +9,139 @@
 #include "Sim/Units/CommandAI/Command.h"
 
 
-/******************************************************************************
- * Command constants
- * @see rts/Lua/LuaConstCMD.cpp
-******************************************************************************/
-
 /***
+ * Command constants.
  * @enum CMD
- * @field FIRESTATE_NONE -1
- * @field MOVESTATE_NONE -1
- * @field STOP 0
- * @field MOVESTATE_HOLDPOS 0
- * @field FIRESTATE_HOLDFIRE 0
- * @field INSERT 1
- * @field MOVESTATE_MANEUVER 1
- * @field FIRESTATE_RETURNFIRE 1
- * @field WAITCODE_TIME 1
- * @field WAITCODE_DEATH 2
- * @field MOVESTATE_ROAM 2
- * @field REMOVE 2
- * @field FIRESTATE_FIREATWILL 2
- * @field FIRESTATE_FIREATNEUTRAL 3
- * @field WAITCODE_SQUAD 3
- * @field OPT_META 4
- * @field WAITCODE_GATHER 4
- * @field WAIT 5
- * @field TIMEWAIT 6
- * @field DEATHWAIT 7
- * @field OPT_INTERNAL 8
- * @field SQUADWAIT 8
- * @field GATHERWAIT 9
- * @field MOVE 10
- * @field PATROL 15
- * @field FIGHT 16
- * @field OPT_RIGHT 16
- * @field LOOPBACKATTACK 20
- * @field ATTACK 20
- * @field AREA_ATTACK 21
- * @field GUARD 25
- * @field OPT_SHIFT 32
- * @field GROUPSELECT 35
- * @field GROUPADD 36
- * @field GROUPCLEAR 37
- * @field REPAIR 40
- * @field FIRE_STATE 45
- * @field MOVE_STATE 50
- * @field SETBASE 55
- * @field INTERNAL 60
- * @field OPT_CTRL 64
- * @field SELFD 65
- * @field SET_WANTED_MAX_SPEED 70
- * @field LOAD_UNITS 75
- * @field LOAD_ONTO 76
- * @field UNLOAD_UNITS 80
- * @field UNLOAD_UNIT 81
- * @field ONOFF 85
- * @field RECLAIM 90
- * @field CLOAK 95
- * @field STOCKPILE 100
- * @field MANUALFIRE 105
- * @field DGUN 105
- * @field RESTORE 110
- * @field REPEAT 115
- * @field TRAJECTORY 120
- * @field RESURRECT 125
- * @field OPT_ALT 128
- * @field CAPTURE 130
- * @field AUTOREPAIRLEVEL 135
- * @field IDLEMODE 145 
  */
 
-
 bool LuaConstCMD::PushEntries(lua_State* L)
 {
+	/*** @field CMD.OPT_ALT 128 */
 	LuaPushNamedNumber(L, "OPT_ALT",      ALT_KEY);
+	/*** @field CMD.OPT_CTRL 64 */
 	LuaPushNamedNumber(L, "OPT_CTRL",     CONTROL_KEY);
+	/*** @field CMD.OPT_SHIFT 32 */
 	LuaPushNamedNumber(L, "OPT_SHIFT",    SHIFT_KEY);
+	/*** @field CMD.OPT_RIGHT 16 */
 	LuaPushNamedNumber(L, "OPT_RIGHT",    RIGHT_MOUSE_KEY);
+	/*** @field CMD.OPT_INTERNAL 8 */
 	LuaPushNamedNumber(L, "OPT_INTERNAL", INTERNAL_ORDER);
+	/*** @field CMD.OPT_META 4 */
 	LuaPushNamedNumber(L, "OPT_META",     META_KEY);
 
+	/*** @field CMD.MOVESTATE_NONE -1 */
 	LuaPushNamedNumber(L, "MOVESTATE_NONE"    , MOVESTATE_NONE    );
+	/*** @field CMD.MOVESTATE_HOLDPOS 0 */
 	LuaPushNamedNumber(L, "MOVESTATE_HOLDPOS" , MOVESTATE_HOLDPOS );
+	/*** @field CMD.MOVESTATE_MANEUVER 1 */
 	LuaPushNamedNumber(L, "MOVESTATE_MANEUVER", MOVESTATE_MANEUVER);
+	/*** @field CMD.MOVESTATE_ROAM 2 */
 	LuaPushNamedNumber(L, "MOVESTATE_ROAM"    , MOVESTATE_ROAM    );
 
+	/*** @field CMD.FIRESTATE_NONE -1 */
 	LuaPushNamedNumber(L, "FIRESTATE_NONE"         , FIRESTATE_NONE         );
+	/*** @field CMD.FIRESTATE_HOLDFIRE 0 */
 	LuaPushNamedNumber(L, "FIRESTATE_HOLDFIRE"     , FIRESTATE_HOLDFIRE     );
+	/*** @field CMD.FIRESTATE_RETURNFIRE 1 */
 	LuaPushNamedNumber(L, "FIRESTATE_RETURNFIRE"   , FIRESTATE_RETURNFIRE   );
+	/*** @field CMD.FIRESTATE_FIREATWILL 2 */
 	LuaPushNamedNumber(L, "FIRESTATE_FIREATWILL"   , FIRESTATE_FIREATWILL   );
+	/*** @field CMD.FIRESTATE_FIREATNEUTRAL 3 */
 	LuaPushNamedNumber(L, "FIRESTATE_FIREATNEUTRAL", FIRESTATE_FIREATNEUTRAL);
 
+	/*** @field CMD.WAITCODE_TIME 1 */
 	LuaPushNamedNumber(L, "WAITCODE_TIME",   CMD_WAITCODE_TIMEWAIT);
+	/*** @field CMD.WAITCODE_DEATH 2 */
 	LuaPushNamedNumber(L, "WAITCODE_DEATH",  CMD_WAITCODE_DEATHWAIT);
+	/*** @field CMD.WAITCODE_SQUAD 3 */
 	LuaPushNamedNumber(L, "WAITCODE_SQUAD",  CMD_WAITCODE_SQUADWAIT);
+	/*** @field CMD.WAITCODE_GATHER 4 */
 	LuaPushNamedNumber(L, "WAITCODE_GATHER", CMD_WAITCODE_GATHERWAIT);
 
 #define PUSH_CMD(cmd) LuaInsertDualMapPair(L, #cmd, CMD_ ## cmd);
 
+	/*** @field CMD.STOP 0 */
 	PUSH_CMD(STOP);
+	/*** @field CMD.INSERT 1 */
 	PUSH_CMD(INSERT);
+	/*** @field CMD.REMOVE 2 */
 	PUSH_CMD(REMOVE);
+	/*** @field CMD.WAIT 5 */
 	PUSH_CMD(WAIT);
+	/*** @field CMD.TIMEWAIT 6 */
 	PUSH_CMD(TIMEWAIT);
+	/*** @field CMD.DEATHWAIT 7 */
 	PUSH_CMD(DEATHWAIT);
+	/*** @field CMD.SQUADWAIT 8 */
 	PUSH_CMD(SQUADWAIT);
+	/*** @field CMD.GATHERWAIT 9 */
 	PUSH_CMD(GATHERWAIT);
+	/*** @field CMD.MOVE 10 */
 	PUSH_CMD(MOVE);
+	/*** @field CMD.PATROL 15 */
 	PUSH_CMD(PATROL);
+	/*** @field CMD.FIGHT 16 */
 	PUSH_CMD(FIGHT);
+	/*** @field CMD.ATTACK 20 */
 	PUSH_CMD(ATTACK);
+	/*** @field CMD.AREA_ATTACK 21 */
 	PUSH_CMD(AREA_ATTACK);
+	/*** @field CMD.GUARD 25 */
 	PUSH_CMD(GUARD);
+	/*** @field CMD.GROUPSELECT 35 */
 	PUSH_CMD(GROUPSELECT);
+	/*** @field CMD.GROUPADD 36 */
 	PUSH_CMD(GROUPADD);
+	/*** @field CMD.GROUPCLEAR 37 */
 	PUSH_CMD(GROUPCLEAR);
+	/*** @field CMD.REPAIR 40 */
 	PUSH_CMD(REPAIR);
+	/*** @field CMD.FIRE_STATE 45 */
 	PUSH_CMD(FIRE_STATE);
+	/*** @field CMD.MOVE_STATE 50 */
 	PUSH_CMD(MOVE_STATE);
+	/*** @field CMD.SETBASE 55 */
 	PUSH_CMD(SETBASE);
+	/*** @field CMD.INTERNAL 60 */
 	PUSH_CMD(INTERNAL);
+	/*** @field CMD.SELFD 65 */
 	PUSH_CMD(SELFD);
+	/*** @field CMD.LOAD_UNITS 75 */
 	PUSH_CMD(LOAD_UNITS);
+	/*** @field CMD.LOAD_ONTO 76 */
 	PUSH_CMD(LOAD_ONTO);
+	/*** @field CMD.UNLOAD_UNITS 80 */
 	PUSH_CMD(UNLOAD_UNITS);
+	/*** @field CMD.UNLOAD_UNIT 81 */
 	PUSH_CMD(UNLOAD_UNIT);
+	/*** @field CMD.ONOFF 85 */
 	PUSH_CMD(ONOFF);
+	/*** @field CMD.RECLAIM 90 */
 	PUSH_CMD(RECLAIM);
+	/*** @field CMD.CLOAK 95 */
 	PUSH_CMD(CLOAK);
+	/*** @field CMD.STOCKPILE 100 */
 	PUSH_CMD(STOCKPILE);
+	/*** @field CMD.MANUALFIRE 105 */
 	PUSH_CMD(MANUALFIRE);
+	/*** @field CMD.DGUN 105 */
 	LuaInsertDualMapPair(L, "DGUN", CMD_MANUALFIRE); // backward compatibility (TODO: find a way to print a warning when used!)
+	/*** @field CMD.RESTORE 110 */
 	PUSH_CMD(RESTORE);
+	/*** @field CMD.REPEAT 115 */
 	PUSH_CMD(REPEAT);
+	/*** @field CMD.TRAJECTORY 120 */
 	PUSH_CMD(TRAJECTORY);
+	/*** @field CMD.RESURRECT 125 */
 	PUSH_CMD(RESURRECT);
+	/*** @field CMD.CAPTURE 130 */
 	PUSH_CMD(CAPTURE);
+	/*** @field CMD.AUTOREPAIRLEVEL 135 */
 	PUSH_CMD(AUTOREPAIRLEVEL);
+	/*** @field CMD.LOOPBACKATTACK 20 */
 	LuaInsertDualMapPair(L, "LOOPBACKATTACK", CMD_ATTACK); // backward compatibility (TODO: find a way to print a warning when used!)
+	/*** @field CMD.IDLEMODE 145  */
 	PUSH_CMD(IDLEMODE);
 
 	return true;
-}
-
-
-/******************************************************************************/
-/******************************************************************************/
+}