Merge pull request #379 from taminomara/docs

Improve documentation generation

README.md

@@ -1,108 +1,62 @@
-FicsIt-Networks [![Build Status](https://jenkins.massivebytes.net/job/FicsIt-Networks/job/master/badge/icon)](https://jenkins.massivebytes.net/job/FicsIt-Networks/job/master)
-===============
-FicsIt-Networks is a mod for Satisfactory, written in C++/BP using Unreal Engine and the Satisfactory Modloader, which allows you to control, monitor, manage and automate each process of your factory by providing a network system and programmable computers, aswell as other I/O.
+# FicsIt-Networks
+
+FicsIt-Networks allows you to control, mointor, manage and automate each process of your factory by providing a network system and programmable computers, aswell as other I/O.
 It is inspired by [OpenComputers](https://github.com/MightyPirates/OpenComputers).
 
 **If you want to learn more:**
 [please visit the Documentation](https://docs.ficsit.app/ficsit-networks/latest)
 [or the SMR Mod page](https://ficsit.app/mod/8d8gk4imvFanRs)
 
-Discord
-=======
-You can join our [discord server](https://discord.gg/3VfZ6Da) where you can get help for using the mod, where you can share your scripts or just simply discuss the mod.
+<a href="https://discord.gg/3VfZ6Da"><img height="50px" src="https://gotpa.ws/img/join_discord.png" /></a>
 
-Work In Progress
-================
-This project is in no finished state!
-We are constantly working on features to make the mod even greater.
+## Development Versions
 
-Want to test the Mod?
-=====================
 If you want to test the mod and so help with development,
 we would reccomend you to join the [FicsIt-Networks Discord Server](https://discord.gg/3VfZ6Da) and contact one of the mod developers for a more in depth help.
 Testing means, it would not be a good idea to use the mod in your normal game state,
 testing means testing the mod in its own world to make sure every features works as intended.
 
 You can download the latest builds:
 
-[ [Latest Stable Version](https://jenkins.massivebytes.net/job/FicsIt-Networks/job/master/) ] 
-[ [Development Version](https://jenkins.massivebytes.net/job/FicsIt-Networks/job/development/) ]
+[ [Latest Stable Version](https://github.com/Panakotta00/FicsIt-Networks/releases/latest) ] 
+[ [Development Versions](https://github.com/Panakotta00/FicsIt-Networks/actions?query=branch%3Adevelopment) ]
 
-To install it, simply download the .zip artifact and extract the contents of it into the `<sf installation>/FactoryGame/Mods/FicsItNetworks` folder.
+To install it, simply download the `FicsItNetworks-Windows.zip` artifact and extract the contents of it into the `<sf installation>/FactoryGame/Mods/FicsItNetworks` folder.
 It has to be this exact path and folder name! Extract it in a way, so the `.uplugin`-File is located within this folder.
 
-Streams
-=======
-The biggest part of making this mod gets streamed at [Panakotta00's Twitch Channel](https://twitch.tv/panakotta00).
-
-You-Tube
-========
-- [Release Trailer](https://www.youtube.com/watch?v=EErI0OiWttw)
-- [Mod Showcase by RandomGamer](https://www.youtube.com/watch?v=EtybEOkgJ4o)
-- [Tutorial Series](https://www.youtube.com/playlist?list=PLKTdAeAt_BilFGjKoIG9GObwjqmxdSoeE)
-- [Lua Tutorial Series](https://www.youtube.com/playlist?list=PLKTdAeAt_BimxLkH05GSNBZpydxc553hE)
-
-Features
-========
-- Networks
-  This is a basic network like the existing power network allowing you to connect buildings with a network connector to the network.
-  When placing a network cable you're also able to automatically add a network adapter to existing Satisfactory Machines to connect them to the network.
-  These networks then allow you to access function from machines and get automatically send signals from machines e.g. no need of polling.
-- Modular Computer
-  The modular computer is a building wich has  network connector and a power connector.
-  The basic concept is, that you have panele were you can place different modules like the cpu, ram-bars or a drive enabling different features for your computer.
-  There is currently one type of processor, the Lua Processor. It allows you to run complex Lua code which uses the network to interact with your factory.
-- Modular I/O Panel
-  The modular I/O Panel is basically a control panel were you can attach different I/O modules like buttons, levers, LEDs, displays and so on. To read and write data to and from a computer.
-- File Systems
-  You can read and write files to and from a virtual file system in f.e. a hard drive which you can connect to a computer by the drive holder computer module.
-- Speakers
-  With the Speaker-Pole you can play custom sound files ingame on command. So you can alert the player automatically when f.e. the Iron stock runs low.
-- Codeable Splitters/Mergers
-  There are also Splitters and Mergers able to connect to the network allowing you to fully customize their behaviour by controlling each step from a computer via. f.e. a lua code.
-- Power Controller
-  The Power Controller Pole is basically a smart power switch allowing you to connect and disconnect two different power networks.
-- Network Adapter
-  The network adapter allows you to connect any satisfactory machine to the network and allow some basic and some more complex interactions like reading inventories.
-- Monitors & GPUs
-  Monitors and GPUs allow you to visualize data in multiple different forms. They also allow you to use montiors as user inputs like Keyboard, Mouse and Touch.
-- Vehicle Scanner
-  Allows to interact with vehicles that pass over it. It also looks nice ;-)
-- Reflection System
-  The Reflection System allows to check data-types, functions, properties, signals and more. You can look up all sort of information and it helps you
-  for a more dynamic way to interact with the machines. This system also provides a abstraction layer so that further language implementations and such can get implemented more
-  easily and quicker. It also provides a dependency-less system so other mods can provide functionality that can be used by ficsit-networks.
-  It also provides the reflection viewer which is UI Widget allowing you to browse and explore the reflection data, like an ingame documentation.
-- Internet Card
-  The Internet Card allows you to connect to the internet so you can do f.e. http requests and download
-  custom user made scripts from f.e. gist or pastebin. But you can use it in anyway, like talking to an REST API.
-- Wireless Networks
-  You can broaden your horizons with Wireless Access Points which connect to already built Radar Towers and allow wireless communications over long distances.
-
-Dependencies
-============
-For using the mod there are no dependencies except the [Satisfactory Modloader](https://github.com/satisfactorymodding/SatisfactoryModLoader) for the game version and mod version you want to use.
-
-As general project build dependency we have Eris for Lua 5.3 to run Lua code and persistency.
-
-Roadmap
-=======
-You can find the detailed progress in the [project board](https://github.com/CoderDE/FicsIt-Networks/projects/1).
-
-- add new sensors (like player sensors)
-- microcontrollers
-- computer power consumption
-- adding support for a visual scripting language
-- port the mod to official mod kit (when released)
-(the list is dynamic and gets updated based on new ideas)
-
-Contributors
-============
-- [Panakotta00](https://panakotta00.massivebytes.net)
+## Features
+
+- **Networks**  
+This is a basic network like the existing power network allowing you to connect buildings with a network connector to the network.
+When placing a network cable you're also able to automatically add a network adapter to existing Satisfactory Machines to connect them to the network.
+These networks then allow you to access function from machines and get automatically send signals from machines e.g. no need of polling.
+- **Modular Computer**  
+The modular computer is a building wich has  network connector and a power connector.
+The basic concept is, that you have panele were you can place different modules like the cpu, ram-bars or a drive enabling different features for your computer.
+There is currently one type of processor, the Lua Processor. It allows you to run complex Lua code which uses the network to interact with your factory.
+- **Modular I/O Panels**  
+The modular I/O Panel is basically a control panel were you can attach different I/O modules like buttons, levers, LEDs, displays and so on. To read and write data to and from a computer.
+- **Screens**  
+Monitors/Monitors and GPUs allow you to visualize data in multiple different forms. They also allow you to use montiors as user inputs like Keyboard, Mouse and Touch.
+- **Extensive API**  
+Most of the games mechanics are exposed to the script environment using the reflection system. The in-game reflection viewer allows you to easily discover exposed functionallity for every machine and most buildings. Even other mods that do not explicity support FicsIt-Networks have some API available to work with.
+- **Lua Scripting**  
+Lua is a first-class-citizen and is used to programm in-game computers. The reflection system and even more API is exposed to the Lua runtime giving you a lot of freedom on how to control your factory.
+
+## Build from Scratch
+1. Setup the Mod-Development Environment for Satisfactory Modding. More info can be found in the [SMR Docs](https://docs.ficsit.app/satisfactory-modding/latest/Development/BeginnersGuide/index.html).
+2. Now you have to clone this repository **recursively** into the Mods folder of the [Satisfactory Modloader](https://github.com/satisfactorymodding/SatisfactoryModLoader) repository folder you cloned in the setup process.
+3. Apply the `SML_Patch.patch` file using `git apply` to the Satisfactory Modloader Repository folder. This will add simple changes to the header files that are necessary for FicsIt-Networks to build properly.
+4. Now you can build FicsIt-Networks like any other Satisfactory Mod using your build tool of choice or Alpakit.
+
+FicsIt-Networks relies on a slightly custom version of Eris for Lua 5.4 to run Lua code and persistency. The changes only apply to C++ compiler support and persistency adjustments. The dependency will be built together with the normal mod, so you only have to ensure the submodule is cloned properly.
+
+## Contributors
+- [Panakotta00](https://panakotta00.dev)
+- [Roze](https://github.com/RozeDoyanawa)
 - [RosszEmber](https://www.deviantart.com/ronsemberg)
 - Deantendo
 - Coffeediction
-- [Roze](https://github.com/RozeDoyanawa)
 - [Raysh](https://www.artstation.com/raysh)
 - Esper
 - [leonardfactory](https://github.com/rockfactory)

Source/FicsItNetworksComputer/Public/ComputerModules/PCI/FINComputerGPUT2.h

@@ -570,7 +570,7 @@ class FICSITNETWORKSCOMPUTER_API AFINComputerGPUT2 : public AFINComputerGPU {
 		ParameterInternalNames.Add("startDirections");
 		ParameterDisplayNames.Add(FText::FromString("Start Direction"));
 		ParameterDescriptions.Add(FText::FromString("The direction of the spline of how it exists the start point."));
-		ParameterInternalNames.Add("end");
+		ParameterInternalNames.Add("end_");
 		ParameterDisplayNames.Add(FText::FromString("End"));
 		ParameterDescriptions.Add(FText::FromString("The local position of the end point of the spline."));
 		ParameterInternalNames.Add("endDirection");

Source/FicsItNetworksDocumentation/Private/CMD/FINCMDGenLuaDoc.cpp

@@ -127,23 +127,26 @@ namespace FINGenLuaDoc {
 		Str.Appendf(TEXT("--- %s\n"), *Description);
 	}
 
-	void WriteFuture(FStringBuilderBase& Str, const FString& TypeIdentifier, const FString& FunctionName, const FString& TypedParameterList) {
+	void WriteFuture(FStringBuilderBase& Str, FFicsItReflectionModule& Ref, const FString& TypeIdentifier, const FString& FunctionName, const TArray<UFIRProperty*>& ReturnValues, bool VariadicReturn) {
 		FString identifier = FString::Printf(TEXT("Future_%s_%s"), *TypeIdentifier, *FunctionName);
 		Str.Appendf(TEXT("---@class %s : Future\n"), *identifier);
 		Str.Appendf(TEXT("%s = {}\n"), *identifier);
 
-		FString returnValues;
-		if (!TypedParameterList.IsEmpty()) {
-			returnValues = FString::Printf(TEXT(":(%s)"), *TypedParameterList);
+		FString returnAnnotation;
+		for (UFIRProperty* returnValue : ReturnValues) {
+			returnAnnotation.Appendf(TEXT("---@return %s %s %s\n"), *GetType(Ref, returnValue), *returnValue->GetInternalName(), *GetInlineDescription(returnValue->GetDescription().ToString()));
+		}
+		if (VariadicReturn) {
+			returnAnnotation.Append(TEXT("---@return any ...\n"));
 		}
 
-		Str.Appendf(TEXT("---@type fun(self:%s)%s\n"), *identifier, *returnValues);
+		Str.Append(returnAnnotation);
 		Str.Appendf(TEXT("function %s:await() end\n"), *identifier);
 
-		Str.Appendf(TEXT("---@type fun(self:%s)%s\n"), *identifier, *returnValues);
+		Str.Append(returnAnnotation);
 		Str.Appendf(TEXT("function %s:get() end\n"), *identifier);
 
-		Str.Appendf(TEXT("---@type fun(self:%s):boolean\n"), *identifier);
+		Str.Appendf(TEXT("---@return boolean\n"), *identifier);
 		Str.Appendf(TEXT("function %s:canGet() end\n"), *identifier);
 	}
 
@@ -170,56 +173,37 @@ namespace FINGenLuaDoc {
 		}
 
 		TArray<FString> paramList;
-		TArray<FString> typedParameterList;
-		typedParameterList.Add(TEXT("self:") + Type);
 		for (UFIRProperty* parameter : parameters) {
 			paramList.Add(parameter->GetInternalName());
-			typedParameterList.Add(parameter->GetInternalName() + TEXT(":") + GetType(Ref, parameter));
 			Str.Appendf(TEXT("---@param %s %s %s\n"), *parameter->GetInternalName(), *GetType(Ref, parameter), *GetInlineDescription(parameter->GetDescription().ToString()));
 		}
 		if (Func->FunctionFlags & FIR_Func_VarArgs) {
 			paramList.Add(TEXT("..."));
-			typedParameterList.Add(TEXT("...:any"));
 			Str.Append(TEXT("---@param ... any\n"));
 		}
 
 		bool bFuture = !(Func->GetFunctionFlags() & FIR_Func_RT_Parallel);
+		bool bVariadicReturn = static_cast<bool>(Func->FunctionFlags & FIR_Func_VarRets);
 
-		TArray<FString> returnValueList;
-		for (UFIRProperty* returnValue : returnValues) {
-			returnValueList.Add(returnValue->GetInternalName() + TEXT(":") + GetType(Ref, returnValue));
-			if (!bFuture) {
+		if (!bFuture) {
+			for (UFIRProperty* returnValue : returnValues) {
 				Str.Appendf(TEXT("---@return %s %s %s\n"), *GetType(Ref, returnValue), *returnValue->GetInternalName(), *GetInlineDescription(returnValue->GetDescription().ToString()));
 			}
-		}
-		if (Func->FunctionFlags & FIR_Func_VarRets) {
-			returnValueList.Add(TEXT("...:any"));
-			if (!bFuture) {
-				Str.Append(TEXT("---@return ... any\n"));
+			if (bVariadicReturn) {
+				Str.Append(TEXT("---@return any ...\n"));
 			}
-		}
-		FString joinedReturnValueList = FString::Join(returnValueList, TEXT(","));
-		FString futureParameterList;
-		if (bFuture) {
+		} else {
 			FString futureTypeIdentifier = FString::Printf(TEXT("Future_%s_%s"), *Type, *Func->GetInternalName());
-			futureParameterList = joinedReturnValueList;
-			joinedReturnValueList = futureTypeIdentifier;
 			Str.Appendf(TEXT("---@return %s\n"), *futureTypeIdentifier);
+			Str.Append(TEXT("---@nodiscard\n"));
 		}
 
-		FString functionTypedReturn;
-		if (!returnValueList.IsEmpty()) {
-			functionTypedReturn = FString::Printf(TEXT(":(%s)"), *joinedReturnValueList);
-		}
-
-		Str.Appendf(TEXT("---@type (fun(%s)%s)|ReflectionFunction\n"), *FString::Join(typedParameterList, TEXT(",")), *functionTypedReturn);
-
 		FString Identifier = Func->GetInternalName();
 
 		Str.Appendf(TEXT("function %s:%s(%s) end\n"), *Parent, *Identifier, *FString::Join(paramList, TEXT(", ")));
 
 		if (bFuture) {
-			WriteFuture(Str, Type, Func->GetInternalName(), futureParameterList);
+			WriteFuture(Str, Ref, Type, Func->GetInternalName(), returnValues, bVariadicReturn);
 		}
 
 		// TODO: Add support for Operator Overloading
@@ -317,11 +301,9 @@ namespace FINGenLuaDoc {
 
 	void WriteLuaFunction(FStringBuilderBase& Str, const FFINLuaFunction& Function, const FString& Identifier) {
 		TArray<FString> parameterList;
-		TArray<FString> typedParameterList;
 		for (const auto& parameter : Function.Parameters) {
 			Str.Appendf(TEXT("---@param %s %s %s\n"), *parameter.InternalName, *parameter.Type, *parameter.Description.ToString());
 			parameterList.Add(parameter.InternalName);
-			typedParameterList.Add(parameter.InternalName + TEXT(":") + parameter.Type);
 		}
 
 		TArray<FString> typedReturnValueList;
@@ -330,12 +312,6 @@ namespace FINGenLuaDoc {
 			typedReturnValueList.Add(returnValue.InternalName + TEXT(":") + returnValue.Type);
 		}
 
-		FString functionReturn;
-		if (!typedReturnValueList.IsEmpty()) {
-			functionReturn = FString::Printf(TEXT(":(%s)"), *FString::Join(typedReturnValueList, TEXT(",")));
-		}
-
-		Str.Appendf(TEXT("---@type (fun(%s)%s)|ModuleTableFunction\n"), *FString::Join(typedParameterList, TEXT(",")), *functionReturn);
 		Str.Appendf(TEXT("function %s(%s) end\n"), *Identifier, *FString::Join(parameterList, TEXT(", ")));
 	}
 
@@ -399,7 +375,8 @@ namespace FINGenLuaDoc {
 		} else if (Metatable.InternalName == TEXT("StructLib")) {
 			FFicsItReflectionModule& reflection = FFicsItReflectionModule::Get();
 			for (auto[Struct, FINStruct] : reflection.GetStructs()) {
-				Str.Appendf(TEXT("---@type fun(table):%s\n"), *FINStruct->GetInternalName());
+				Str.Append(TEXT("---@param t table\n"));
+				Str.Appendf(TEXT("---@return %s\n"), *FINStruct->GetInternalName());
 				Str.Appendf(TEXT("function StructLib.%s(t) end\n"), *FINStruct->GetInternalName());
 			}
 		}
@@ -425,6 +402,7 @@ namespace FINGenLuaDoc {
 	FString GenDocumentation() {
 		FStringBuilderBase str;
 
+		str.Append(TEXT("---@diagnostic disable: missing-fields\n"));
 		str.Append(TEXT("---@meta\n\n"));
 
 		const auto& moduleRegistry = FFINLuaModuleRegistry::GetInstance();

Source/FicsItNetworksLua/Private/FINLua/API/LuaComputerAPI.cpp

@@ -30,12 +30,12 @@ namespace FINLua {
 			}
 
 			LuaModuleTableFunction(R"(/**
-			 * @LuaFunction		(int, string, string)		magicTime()
+			 * @LuaFunction		(integer, string, string)		magicTime()
 			 * @DisplayName		Magic Time
 			 *
 			 * Returns some kind of strange/mysterious time data from a unknown place (the real life).
 			 *
-			 * @return	unix			int		Unix			Unix Timestamp
+			 * @return	unix			integer	Unix			Unix Timestamp
 			 * @return	cultureTime		string	Culture Time	The time as text with the culture format used by the Host
 			 * @return	iso8601			string	ISO 8601		The time as a Date-Time-Stamp after ISO 8601
 			 */)", magicTime) {

Source/FicsItNetworksLua/Private/FINLua/API/LuaDebugAPI.cpp

@@ -19,7 +19,7 @@ namespace FINLua {
 			 *
 			 * Allows to log the given strings to the Game Log.
 			 *
-			 * @param	msgs	string...	A list of log messages that should get printed to the game console.
+			 * @param		...			string		Messages	A list of log messages that should get printed to the game console.
 			 */)", log) {
 				int args = lua_gettop(L);
 				FString Msg;