Documentation

[ghost]

For a game engine like this, there can be a bit of documentation regarding the use of API to make it easier to use for first time developers wanting to try it out.

[metablaster]

Tutorials are always welcome ofc, however I prefer documentation in code, ex. doxygen style.

description of a class/function/variable etc. is of much higher worth than some online wiki or friendly tutorial.

Here is an example snapshot from my project to show how I document my code because examples tell more than just bare words:

/**
 * @file UI\BaseWindow.hpp
 *
 * BaseWindow class declaration
 *
 */

#pragma once
#include "framework.hpp"
#include "object.hpp"		// parent class
#include "ObjectPtr.hpp"	// member, parameter
#include "menu.hpp"		// parameter
#include "MenuItem.hpp"		// forward declared

/**
 * @brief user interface classes and functions
*/
namespace wsl::ui
{
	/**
	* BaseWindow is an abstract base class from which all window type classes inherit
	* it defines basic message processing functions, common data and functions.
	*/
	class UI_API BaseWindow :
		virtual public Object
	{
		//
		// Setters and getters
		//
	public:

		/** Set window title */
		virtual bool SetCaption(PCWSTR caption) noexcept;

		/**
		* Set window MINMAXINFO struct
		* This structure is used to define window sizing limits
		*/
		inline virtual void SetMinMaxInfo(const MINMAXINFO& info) noexcept;

		/**
		* Query current MINMAXINFO from the window
		* This structure is used to define window sizing limits
		*/
		inline virtual void GetMinMaxInfo(MINMAXINFO& info) const noexcept;

		/**
		* @brief Handler for WM_CLOSE
		* A window with a window menu (WS_SYSMENU) receives a WM_CLOSE message when the user clicks Close.
		* By default, the DefWindowProcW function calls the DestroyWindow function to destroy the window.
		* The DestroyWindow function sends WM_DESTROY and WM_NCDESTROY messages to the window
		* If an application processes this message, it should return zero.
		* @return If the function succeeds, the return value is true.
		*/
		inline virtual bool OnClose();

		/**
		* @brief Handler for WM_DESTROY
		* sent before the child windows are destroyed.
		* It is sent to the window procedure of the window being destroyed after the window is removed from the screen.
		* This message is sent first to the window being destroyed and then to the child windows (if any)
		* If an application processes this message, it should return zero.
		*/
		[[nodiscard]] inline virtual LRESULT OnDestroy() const NOEXCEPT;

		//
		// Members
		//
	protected:
		/** Window style flags */
		DWORD mWindowStyle;

		/** Extended window style flags */
		DWORD mWindowExStyle;

		/**
		* @brief Window title for derived component.
		* Only CreateDialogTemplate requires std::wstring,
		* all other functions expect PCWSTR
		*/
		PCWSTR mCaption;

		/** Window handle of derived component */
		HWND mhWnd;
}

Of course this is absolutely required for header files in any project not only here, while source files should only document critical sections of code that is otherwise not self explanatory or to separate sections of code for readability (which btw. you already do, great job!), once a symbol is well documented the rest becomes self explanatory even to complete beginners.

I'm sure you like my approach to document code as much as I like the discovery of your awesome game engine (@PanosK92 ) on which I'm going to work for sure, and once I familiarize myself with the code there is no doubt I'll also write code comments for documentation, but likely not anytime soon.

EDIT: Dxygen and doxygen commenting syntax official site is here: https://www.doxygen.nl/index.html

[ghost]

Yeah, I totally agree, but I won't be able to provide docs for this engine because...

• I am working on my own project: Cylvre,
• I am not really that good with C++

I opened this issue because this is a really good engine and it would become better if someone provided docs on it, which is what most other game engines on GitHub lack/not provide properly.

[PanosK92]

I agree, code-based documentation is great.

Keep in mind that the engine is constantly evolving, so it can be tricky to document it, I'll try to improve this area though.