fix: add parser doc for c++ module

Author: qubka

content/4.languages/2.cpp/3.export-functions.md

@@ -248,14 +248,248 @@ extern "C" PLUGIN_API void ExecuteWithCallback_Exported_Name(int32_t value, cons
 ```
 ::
 
+## **Automating Manifest Generation**
+
+::callout{icon="i-lucide-sparkles" color="blue"}
+**New:** You can now automate the generation of the `methods` section in your plugin manifest using clang-doc and a Python parser!
+::
+
+Instead of manually writing the manifest JSON for each exported function, you can use automated tools to extract function signatures, types, parameter descriptions, and even enum definitions directly from your C++ source code.
+
+### **Benefits of Automated Generation**
+
+1. **No Manual JSON Writing**: Function signatures are automatically extracted from your code
+2. **Complete Type Information**: Enum structures and function typedefs are included automatically
+3. **Documentation Integration**: Doxygen comments are parsed and included in the manifest
+4. **Reduced Errors**: Eliminates typos and type mismatches between code and manifest
+5. **Easy Maintenance**: Changes to function signatures are automatically reflected
+
+### **Setup: Adding Documentation Generation to CMake**
+
+Add the following to your `CMakeLists.txt` to generate documentation and manifest JSON:
+
+```cmake
+# Find clang-doc (usually comes with LLVM/Clang installation)
+find_program(CLANG_DOC clang-doc)
+
+if(CLANG_DOC)
+    # Generate YAML documentation from your exported functions
+    add_custom_target(docs
+        COMMAND ${CLANG_DOC}
+            --executor=all-TUs
+            -p ${CMAKE_CURRENT_BINARY_DIR}
+            --output=${CMAKE_CURRENT_SOURCE_DIR}/docs
+            --extra-arg=-Wno-error
+            --format=yaml
+            ${CMAKE_SOURCE_DIR}/src/export/*.cpp  # Path to your exported functions
+        WORKING_DIRECTORY ${CMAKE_BINARY_DIR}
+        COMMENT "Generating documentation with clang-doc"
+    )
+    
+    # Optional: Automatically parse YAML to JSON after docs generation
+    find_package(Python3 COMPONENTS Interpreter)
+    if(Python3_FOUND)
+        add_custom_command(TARGET docs POST_BUILD
+            COMMAND ${Python3_EXECUTABLE} 
+                    ${CMAKE_SOURCE_DIR}/tools/parser.py
+                    ${CMAKE_SOURCE_DIR}/docs/index.yaml
+                    ${CMAKE_SOURCE_DIR}/exported_methods.json
+            COMMENT "Parsing documentation to JSON"
+        )
+    endif()
+endif()
+```
+
+### **Using the Parser**
+
+::steps{level=4}
+#### **Install the Parser**
+
+Download `parser.py` and place it in your project (e.g., in a `tools/` directory).
+
+Install dependencies:
+```bash
+pip install pyyaml
+```
+
+:read-more{icon="lucide:github" to="https://github.com/untrustedmodders/plugify-module-cpp/tree/main/tools/parser" title="GitHub Repository"}
+
+#### **Document Your Functions**
+
+Add Doxygen comments to your exported functions:
+
+```cpp
+/**
+ * @brief Creates a console command as an administrative command.
+ * If the command does not exist, it is created. When this command is invoked,
+ * the access rights of the player are automatically checked before allowing it to continue.
+ * 
+ * @param name The name of the console command.
+ * @param adminFlags The admin flags that indicate which admin level can use this command.
+ * @param description A brief description of what the command does.
+ * @param flags Command flags that define the behavior of the command.
+ * @param callback A callback function that is invoked when the command is executed.
+ * @param mode Whether the hook was in post mode (after processing) or pre mode (before processing).
+ * @return A boolean indicating whether the command was successfully added.
+ */
+extern "C" PLUGIN_API bool AddAdminCommand(
+    const plg::string& name,
+    int64_t adminFlags,
+    const plg::string& description,
+    ConVarFlag flags,
+    CommandCallback callback,
+    HookMode mode
+);
+```
+
+#### **Document Enums and Typedefs**
+
+Document your enums and function typedefs:
+
+```cpp
+/**
+ * @brief Enum representing the type of callback.
+ */
+enum class HookMode : uint8_t {
+    /** Callback will be executed before the original function */
+    Pre = 0,
+    /** Callback will be executed after the original function */
+    Post = 1
+};
+
+/**
+ * @brief Handles the execution of a command triggered by a caller.
+ * This function processes the command, interprets its context, and handles any provided arguments.
+ */
+using CommandCallback = ResultType (*)(int32_t caller, CommandCallingContext context, const plg::vector<plg::string>& arguments);
+```
+
+#### **Generate Documentation**
+
+Build the documentation target:
+```bash
+cmake --build . --target docs
+```
+
+This generates `docs/index.yaml` with all your function information.
+
+#### **Parse to JSON**
+
+Run the parser to convert YAML to the manifest format:
+```bash
+python3 tools/parser.py docs/index.yaml exported_methods.json
+```
+
+Or with filtering:
+```bash
+# Only functions from files starting with "commands"
+python3 tools/parser.py docs/index.yaml exported_methods.json --file-prefix "commands"
+
+# Only functions with "Admin" in their name
+python3 tools/parser.py docs/index.yaml exported_methods.json --name-filter "Admin"
+```
+
+#### **Use in Your Manifest**
+
+Copy the generated `methods` array from `exported_methods.json` into your plugin manifest:
+
+```json
+{
+  "name": "ExamplePlugin",
+  "version": "1.0.0",
+  "methods": [
+    // Paste the content from exported_methods.json here
+  ]
+}
+```
+::
+
+### **Advanced: Enum Structures**
+
+The parser automatically includes complete enum definitions when a parameter uses an enum type:
+
+**Generated Output:**
+```json
+{
+  "name": "mode",
+  "type": "uint8",
+  "description": "Whether the hook was in post mode or pre mode.",
+  "enum": {
+    "name": "HookMode",
+    "description": "Enum representing the type of callback.",
+    "values": [
+      {
+        "name": "Pre",
+        "value": 0,
+        "description": "Callback will be executed before the original function"
+      },
+      {
+        "name": "Post",
+        "value": 1,
+        "description": "Callback will be executed after the original function"
+      }
+    ]
+  }
+}
+```
+
+### **Advanced: Function Typedefs**
+
+Function pointer typedefs are automatically parsed into complete prototypes:
+
+**Generated Output:**
+```json
+{
+  "name": "callback",
+  "type": "function",
+  "description": "A callback function that is invoked when the command is executed.",
+  "prototype": {
+    "name": "CommandCallback",
+    "funcName": "CommandCallback",
+    "description": "Handles the execution of a command triggered by a caller.",
+    "paramTypes": [
+      {
+        "name": "param1",
+        "type": "int32"
+      },
+      {
+        "name": "param2",
+        "type": "int32",
+        "enum": {
+          "name": "CommandCallingContext",
+          "values": [...]
+        }
+      },
+      {
+        "name": "param3",
+        "type": "string[]"
+      }
+    ],
+    "retType": {
+      "type": "int32",
+      "enum": {
+        "name": "ResultType",
+        "values": [...]
+      }
+    }
+  }
+}
+```
+
+::callout{icon="i-lucide-info" color="amber"}
+**Note:** Function typedef parameter names are auto-generated as `param1`, `param2`, etc. You may want to customize these in the manifest for better documentation.
+::
+
 ## **Best Practices**
 
 1. **Use `PLUGIN_API`**: Always use the `PLUGIN_API` macro to mark functions for export.
 2. **Follow Type Conventions**: Adhere to Plugify's type conventions for parameters and return values.
-3. **Document Your Functions**: Clearly document the purpose, parameters, and return values of exported functions.
-4. **Test Thoroughly**: Test your exported functions to ensure they work as expected when called by other plugins.
-5. **Update the Manifest**: Always describe exported functions in the plugin manifest under the `methods` section.
+3. **Document Your Functions**: Use Doxygen-style comments (`@brief`, `@param`, `@return`) to document exported functions.
+4. **Automate When Possible**: Use the clang-doc parser to automate manifest generation and reduce manual errors.
+5. **Document Enums and Typedefs**: Include Doxygen comments on enums and typedefs for complete manifest generation.
+6. **Test Thoroughly**: Test your exported functions to ensure they work as expected when called by other plugins.
+7. **Keep Manifests Updated**: If using manual manifests, ensure they stay synchronized with your code. If using automation, regenerate after changes.
 
 ## **Conclusion**
 
-Exporting functions in C++ plugins is straightforward when you follow Plugify's conventions and best practices. By using the `PLUGIN_API` macro, adhering to type conventions, and describing functions in the plugin manifest, you can create robust and interoperable plugins. For more advanced use cases, such as handling callbacks or returning C++ objects, use the techniques outlined in this guide.
+Exporting functions in C++ plugins is straightforward when you follow Plugify's conventions and best practices. By using the `PLUGIN_API` macro, adhering to type conventions, and optionally automating manifest generation with clang-doc and the Python parser, you can create robust and interoperable plugins with minimal manual effort. For more advanced use cases, such as handling callbacks or working with enums, the automated parser provides complete type information including enum structures and function prototypes.

content/4.languages/2.cpp/4.import-functions.md

@@ -16,7 +16,7 @@ Plugify provides a Python script (`generator.py`) to automatically generate head
 #### **Locate the Generator Script**:
 - The `generator.py` script is located in the `generator` folder of the C++ language module.
 
-:read-more{icon="lucide:link" to="https://github.com/untrustedmodders/plugify-module-cpp/tree/main/generator" title="GitHub Repository"}
+:read-more{icon="lucide:link" to="https://github.com/untrustedmodders/plugify-module-cpp/tree/main/tools/generator" title="GitHub Repository"}
 
 #### **Run the Generator Script**:
 - Open a terminal or command prompt and navigate to the folder containing `generator.py`.