This guide describes how documentation should be written. It also explains what should be documented or not, and why.
The goal of this documentation is to share acquired knowledge about the codebase. It is not useful to document every single class and functions of this entire codebase.
Guidelines below are not hard rules that you must absolutely and always follow. The purpose is to give you (and contributors) a common ground to start from.
One big rule is to add documentation when a class / a function is not explicit.
For example, the name of the class PreventionSystem is not clear for someone who only played the game. In this case it is useful to add a sentence describing that Prevention means NCPD / the police.
DO add documentation to describe a behavior that is not already explicit.
DON'T add documentation about a class like PlayerPuppet, only to say "Class of the player".
DON'T add documentation about a function like IsMoving, only to say "Return true when player is moving, false otherwise".
One phrase, one idea.
Reading is hard, keep it as short as possible. Below are patterns you can reuse to structure your comment:
When a general description is somehow required and useful to provide context.
Short description (up to 3 phrases).
Elaborate description (optional, when short description is not enough to fit knowledge).
Provide related resources / references (optional, when related and newcomers are not aware of it).
When behavior is already explicit, but an argument requires a description and more information like a default value, list of known values, etc.
Short description (optional).
Argument with description and optionally the default value / a list of known values.
Patterns above are propositions. It is easier as a reader to see and read documentation when it uses the same format everywhere. It might take a bit of an effort to get used to it as a writer.
This documentation is not about showing how to use a snippet of code: be it in Redscript, Lua or else. In this spirit, writing code in the documentation should be avoided. If it is deemed really useful, it should be as short as possible.
More than often, people played the game and knows about the vocabulary it uses. It is preferable to use game's vocabulary to be on the same page.
For example, it is preferred to tell Prevention is about NCPD. This way, when you document other parts of the game related to Prevention, you can use the keyword NCPD. Others will understand what you're talking about.
As another example, you can write V when talking about the PlayerPuppet. It should be explicit for anyone, and is shorter to write than the player.
A function might need some kind of predefined data as arguments. Think about the CName type, it is a string-like type but values are not listed like enums. We don't know about them. In this case, a modder will have to dig and search what values the function accepts as a CName.
If you know all or even only one valid value, you should list them when documenting the function. This way, others know what data to use when they need to call this function too.
If the list of values is very big, use a link instead to reference some Sheet-like document containing all known values.
If the list of values is accessible using WolvenKit, add a note about it and provide the path where to look for the data.
An argument of a function is optional when marked with the opt prefix. It can be helpful to describe what default value is used. It can look like this:
In the codebase, you can find features that are not related to the gameplay, saves, the world, etc. For example, you should not care nor mess around with the TelemetrySystem.
In this case, you can add the comment "CDPR only". It is short and explicit enough to tell other modders:
There is nothing to see for modding purpose.
After reading this, you should better grasp what you can document and how. Don't hesitate to go through the current documentation. It can be helpful to see how other parts are already documented, to get more familiar with these guidelines.
is already present to share knowledge about the code and scripting in general. You should share your findings in this space, not in this documentation.