Comments (3)
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
from spartanengine.
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.
from spartanengine.
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.
from spartanengine.
Related Issues (20)
- Wiki documentation
- Improve screen space subsurface scattering for vegetation HOT 1
- Stair navigation in the Doom default world with the physics-based camera
- Ray traced reflections
- Ray traced shadows
- Eye adaptation
- Skeletal animation
- Dynamic resolution scaling HOT 1
- Switch to bindless HOT 2
- Complete D3D12 backend
- Occlusion culling HOT 1
- Crash on Choosing World from World Selection Dialog Box HOT 10
- Improve of editor design/style using imgui
- vulkan destory problem. HOT 4
- Can't open the sponza scene HOT 1
- Vulkan_SwapChain Resize Window has a problem, is made fence wait timeout. so need reset m_sync_index = std::numeric_limits<uint32_t>::max(); HOT 2
- Bug: opening a world crashes the engine HOT 2
- Create Volume Component
- Fix point light shadow mapping HOT 1
- Git: Clean up .git folder to reduce repo size HOT 1
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from spartanengine.