This guide explains the structure to follow when writing documentation for NativeDB.
One sub-page = one class
One sub-page = one struct
Sub-page of a class or a struct must be within page "CLASSES".
Order sub-pages alphabetically (from A to Z).
It is useful to quickly navigate between classes and to add new classes.
You have to follow a small set of rules to write documentation about a class. The format described below is required to show the documentation in NativeDB.
A minimal example shows you how it should look like with Markdown, at the end of this guide.
Option "Page description" must be turned off in "Page options". You can find the feature when moving your mouse over the title of the page.
Title of the page must be the native name of the class. You can configure code syntax in NativeDB with option Pseudocode · Legacy to only show native names.
DO write vehicleBaseObject
DON'T write VehicleObject
Add header "Description" using block "Heading 1".
DO write Description
DON'T write anything else, like descriptionS
After this header, you can add content (like a paragraph) to describe useful knowledge about the class. It will be visible like this in NativeDB:
Add header "Functions" using block "Heading 1", if it doesn't exist already. You can then add functions after this header, as described below.
DO write Functions
DON'T write anything else, like Methods
Add a function using block "Heading 3". This header must be the signature of the function using the Pseudocode · Legacy code syntax.
If the signature of the function is not valid, you're change request will not be merged.
You should use the feature provided by NativeDB to quickly copy the signature of a function in your clipboard. You can do so like this:
As an example with the function FindEntityById, it will look like this in your clipboard, ready to paste in GitBook:
Like with the description, you can then add content below the header of the function to describe it.
You don't have to write both sections (Description and Functions) when creating a new class. You need to at least add one of the two sections, be it Description or Functions.
When present, the section Description must be at the very top of the page.
You're ready to go on with the next guide:
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.
This guide will give you a tour of everything you need to know to document the codebase of NativeDB.
This space is used to write and store documentation. It will synchronize the data in a GitHub repository. NativeDB get the documentation from this repository to show it when browsing the codebase.
GitHub Api limits free access to 60 requests per hour. It doesn't require you to login with a GitHub account from NativeDB. It should be good enough for now.
If you never used GitBook before, you'll see that it is easy to use after learning some basics. to learn you're way around.
NativeDB provides buttons to quickly open GitBook in the right place:
NativeDB expects a custom format and structure to get the data from GitBook, and to show it as beautifully as possible. You first need to learn a few rules, you can start with this guide. It will also explain some guidelines on what to write or not when documenting.
Now that you made a change request, wrote some documentation, you can request a review. An administrator will check it, and if it is alright, merge your change request.
NativeDB will store the documentation in your browser as a cache. It helps improve performance and it reduces the usage of the network's bandwidth. It will only refresh the list of documented classes every 10 minutes (to see if there are changes to update locally). If NativeDB is already open, it will not show your last merged change request. You can wait up to 10 minutes or hit F5 to refresh your tab.
Thank you for your contributions!
If you get lost, If you think a guide lack information, If you think a guide is not clear enough, If you have any other feedback to share,
Please do reach us on Discord in the NativeDB@wiki channel.
This guide explains what syntax you can use to format the documentation for NativeDB.
🟢 fully supported
🟠 partially supported
🔴 not supported
| Blocks | Markdown | Description | |
|---|---|---|---|
Don't hesitate to look at other classes to see how the syntax is used, and how it looks like in NativeDB. If you are not sure, you can always come and ask on Discord.
The following example is only made to show all possible syntax options. There is nothing related to the game:
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.
Paragraph
🟢
Some text
Basic block to show text.
Code
🟢
`content`
Useful to highlight arguments of a function.
Note: it doesn't support complex code block with a language (like ```lua ```).
URL
🟢
[label](https://)
You can add URL link with a label. URL must starts with https://.
Lists
🟠
- Item A
- Item B
1. Item 1
2. Item 2
You can add ordered lists, unordered lists and tasks lists. In all cases, they will be visible as unordered lists using - as a prefix.
Note: you must not add newlines per item. It is not supported for now and formatting will not work as expected in NativeDB.
Markdown example will look like this: - Item A - Item B - Item 1 - Item 2 - Item T - Item D
Bold / Italic
🔴
**bold**
*italic*
Headers
🔴
# H1 ## H2 ### H3
Hint
🔴
{% hint %} {% endhint %}
Class reference
🟢
[ClassName]
Write the native name / alias name of a class between brackets ([]). NativeDB will automatically format it as a link to navigate to the class.
Property reference
🟢
[this.prop] [ClassName.prop]
When documenting a class, you can reference its own properties using this. followed by the name of the property.
You can also reference properties of other classes using ClassName. instead of this..
It must be surrounded by brackets ([]) in both cases.
Function reference
🟢
[this.GetStuff] [ClassName.SetStuff]
When documenting a class, you can reference its own functions using this. followed by the name of the function.
You can also reference functions of other classes using ClassName. instead of this..
It must be surrounded by brackets ([]) in both cases.
Enum / Bitfield reference
🟢
[Enum.Value] [Bitfield.Value]
You can reference value of an enum and value of a bitfield.
