Port docs from PH

CONTRIBUTING.md

@@ -2,7 +2,14 @@
 - [Project structure](#project-structure)
 - [Decompiling](#decompiling)
 - [Code style](#code-style)
-- [Creating new `.c`/`.cpp` files](#creating-new-ccpp-files)
+  - [Naming new things](#naming-new-things)
+  - [Creating a class](#creating-a-class)
+<!-- - [Creating new `.c`/`.cpp` files](#creating-new-ccpp-files) -->
+
+## Decompiling
+[/docs/decompiling.md](/docs/decompiling.md) has most information as to how to approach decompilation and how to get started.
+
+Reading the rest of this file gives information on the structure of the project and coding style, it is highly recommended to read it.
 
 ## Project structure
 - `build/`: Build output
@@ -25,11 +32,68 @@
     - `mangle.py`: Shows mangled symbol names in a given C/C++ file
     - `requirements.txt`: Python libraries
     - `setup.py`: Sets up the project
+    - `vtable_sym.py`: Renames and relocates vtable symbols
 - `*.sha1`: SHA-1 digests of different versions of the game
 
-## Decompiling
-See [/docs/decompiling.md](/docs/decompiling.md).
-
 ## Code style
 This project has a `.clang-format` file and all C/C++ files in this project should follow it. We recommend using an editor
 compatible with `clang-format` to format the code as you save.
+
+As a rule of thumb, try to mimick the style that can be observed in already decompiled files. Please write hexadecimal numbers in upper case (`0x9ABCDEF` instead of `0x9abcdef`). Lowercase is used for global names (functions, data, etc), class members use uppercase too (e.g., `mUnk_04` for a member placed at position `0x4`).
+
+### Naming new things
+
+You may have to create new classes, structs, member attributes or functions, etc. Here is described how to name them according to what they are.
+
+Once you find out what something does, it helps to give it a meaningfull name (eg. `ModelRender` class, `Actor::isAlive()` function or `Actor.mPrevPos` member attribute).
+
+If you don't know yet what a piece of code does, try to follow this rough format: `{type}_ov{num}_{address}`.  
+- `type` is the kind of code you're naming, `UnkStruct` for a struct, `mUnk` for a member attribute, `Unk{D}System{X}` for a class or group of functions. In the last case, `X` would then be an arbitrary, unique identifier. Likely a number that would increase for every new `System` to name. `D` is optional and aimed to give more information about the context in which the system is used (eg. `File` or `Actor`).
+- `num` is the id of the overlay the code is part of.
+- `address` is the address of the data you're naming. This may not always be applicable, in which case you can ignore it (and remove the trailing `_` of the format given above).
+
+You can also name thing based on where they are used. Say that some class `ActorP` has a member `mUnk_{X}` that needs it class, you can call the class `UnkStruct_ActorP_{X}`. Same goes for functions (but try to rather name things with their vtable address when applicable, so that they are easier to find and merge later on).
+
+### Creating a class
+If you are to create a new class, try to follow this structure:
+```cpp
+class Foo {
+public:
+    /* 00 */ int mBar;
+    /* 04 */
+
+    Foo();
+
+    /* 00 */ virtual void vfunc_00();
+    /* 04 */ virtual void vfunc_04();
+    /* 08 */ virtual ~Foo();
+    /* 0C */
+
+    // itcm
+    bool func_01fff1e0();
+
+    // overlay 0
+    void func_ov000_0208a318(unk32 param1, unk32 param2, unk32 param3);
+    void func_ov000_0208bbd4(unk32 param1, VecFx32 *param2, u16 param3);
+
+    static UnkStruct_027e0ce0_34 *func_ov000_0205c904();
+
+    // overlay 1
+    void func_ov001_020bc5f8();
+    void func_ov001_020bc524(bool param1);
+
+    static Foo *Create();
+    static void Destroy();
+
+    // overlay 17
+    void func_ov017_020bd69c();
+};
+```
+
+In order, the parts are:
+- Member attributes.
+- Constructor (ctor).
+- Virtual functions (the placement of the destructor (dtor), if there is any, can vary).
+- Other methods, grouped by overlay with a comment indicating which one.
+
+Using `private` may sometime be required to enable some inlining, so feel free to when use it you feel like you should.

INSTALL.md

@@ -5,41 +5,44 @@ Contents:
 - [Prerequisites](#prerequisites)
 - [Build the ROM](#build-the-rom)
     - [Matching the base ROM](#matching-the-base-rom)
-    - [Building with non-matching code](#building-with-non-matching-code)
+    <!-- - [Building with non-matching code](#building-with-non-matching-code) -->
 - [[Optional] LSP setup](#lsp-setup)
 
 ## Prerequisites
 
 1. Use one of these platforms:
     - Windows (recommended)
     - Linux
-2. Install the following:
+1. Install the following:
     - Python 3.11+ and pip
     - GCC 9+
     - Ninja
-3. Install the Python dependencies:
-```shell
-python -m pip install -r tools/requirements.txt
-```
-4. Install pre-commit hooks:
-```shell
-pre-commit install
-```
-5. Run the Ninja configure script:
-```shell
-python tools/configure.py
-```
-By default this will configure for any version that has a baserom in the `extract` folder (see below), to configure for one specific version:
-```shell
-python tools/configure.py [--version | -v] <eur|jp>
-```
-6. Put one or more base ROMs in the [`/extract/`](/extract/README.md) directory of this repository.
+1. Clone the Github repository on your machine and go to the root of the project.
+1. Install the Python dependencies:
+    ```shell
+    python -m pip install -r tools/requirements.txt
+    ```
+1. Install pre-commit hooks:
+    ```shell
+    pre-commit install
+    ```
+1. Run the Ninja configure script:
+    ```shell
+    python tools/configure.py
+    ```
+    By default this will configure for any version that has a baserom in the `extract` folder (see below), to configure for one specific version:
+    ```shell
+    python tools/configure.py [--version | -v] <eur|jp>
+    ```
+1. Put one or more base ROMs in the [`/extract/`](/extract/README.md) directory of this repository. See the [README.md](/extract/README.md) of that directory for file naming instructions.
 
 Now you can run `ninja` to build a ROM for the chosen version.
 
 > [!NOTE]
 > For Linux users: Wibo is used by default. If you want to use Wine instead, run `configure.py` with `-w <path/to/wine>`.
 
+## Build the ROM
+
 ### Matching the base ROM
 
 **This is optional!** You only need to follow these steps if you want a matching ROM.
@@ -58,9 +61,9 @@ ARM7 BIOS in the root directory of this repository, and verify that your dumped
 
 The repository contains a [`CMakeLists.txt`](CMakeLists.txt) that allows generating a compilation database. For now, the `CMakeLists.txt` can only be used to generate `compile_commands.json` and similar files, not compiling the project.  
 To generate the compilation database, run `cmake -S . -G "Unix Makefiles" -B cmake` from the root directory of the project. This will create a `cmake/` directory that contains the `compile_commands.json`.  
-Once the file is generated, you can dynamically link it to the root directory and let your LSP detect it (make sure not to `git add` it though), or edit your `.clangd` as follows for it to recognize the compilation database:
+Once the file is generated, you can dynamically link it to the root directory and let your LSP detect it (make sure not to `git add` it though, even though the project's `.gitignore` should prevent it), or edit your `.clangd` as follows for it to recognize the compilation database:
 ```clangd
 CompileFlags:
-    CompilationDatabase: "cmake"
+    CompilationDatabase: "cmake"  # path to the compilation database
 ```
 This setup is adapted from a [tutorial by Strus](https://gist.github.com/Strus/042a92a00070a943053006bf46912ae9), refer to his post for further details.

README.md

@@ -9,8 +9,7 @@ The Legend of Zelda: Spirit Tracks
 [Discord Badge]: https://img.shields.io/discord/688807550715560050?color=%237289DA&logo=discord&logoColor=%23FFFFFF
 [discord]: https://discord.com/invite/DqwyCBYKqf/
 
-**Work in progress!** This project aims to recreate source code for ***The Legend of Zelda: Spirit Tracks*** by decompiling its code by hand. **The repository does not contain assets or assembly code.** To build the ROM, you must own an existing
-copy of the game to extract assets from.
+**Work in progress!** This project aims to recreate source code for ***The Legend of Zelda: Spirit Tracks*** by decompiling its code by hand. **The repository does not contain assets or assembly code.** To build the ROM, you must own an existing copy of the game to extract assets from.
 
 > [!NOTE]
 > The project targets the European and Japanese versions, and other versions might be supported later.
@@ -19,7 +18,7 @@ copy of the game to extract assets from.
 See [INSTALL.md](INSTALL.md) for instructions on how to install the project.
 
 ## Contribution
-A work in progress, but [CONTRIBUTING.md](CONTRIBUTING.md) has guidelines for how to contribute to the project.
+A work in progress, but [CONTRIBUTING.md](CONTRIBUTING.md) has guidelines for how to get started and contribute to the project. Make sure to follow instructions on [installation](#how-to-install) first.
 
 ## Documentation
-See [/docs](/docs) for documentation about the game.
+See [/docs](/docs) for documentation about the game and other useful information about the project.