Synced docs for decomped functions

include/dungeon_random.h

@@ -1,7 +1,14 @@
 #ifndef PMDSKY_DUNGEON_RANDOM_H
 #define PMDSKY_DUNGEON_RANDOM_H
 
+// Returns the result of a possibly biased coin flip (a Bernoulli random variable) with some success probability p, using the dungeon PRNG.
+// percentChance: success percentage (100*p)
+// return: true with probability p, false with probability (1-p)
 u8 DungeonRandOutcome__022EAB20(s32 percentChance);
+
+// Returns the result of a possibly biased coin flip (a Bernoulli random variable) with some success probability p, using the dungeon PRNG.
+// percentChance: success percentage (100*p)
+// return: true with probability p, false with probability (1-p)
 u8 DungeonRandOutcome__022EAB50(s32 percentChance);
 
 #endif //PMDSKY_DUNGEON_RANDOM_H

include/main_pack.h

@@ -3,12 +3,46 @@
 
 #include <files/pack.h>
 
+// Open the 6 files at PACK_FILE_PATHS_TABLE into PACK_FILE_OPENED. Called during game initialisation.
 void OpenAllPackFiles(void);
+
+// Call GetFileLengthInPack after looking up the global Pack archive by its number
+// pack_id: pack file number
+// file_index: file number
+// return: size of the file in bytes from the Pack Table of Content
 u32 GetFileLengthInPackWithPackNb(enum pack_file_id pack_id, u32 file_index);
+
+// Call LoadFileInPack after looking up the global Pack archive by its identifier
+// pack_id: pack file identifier
+// file_index: file index
+// output_buffer: [output] target buffer
+// return: number of read bytes (identical to the length of the pack from the Table of Content)
 u32 LoadFileInPackWithPackId(enum pack_file_id pack_id, u32 file_index, void* output_buffer);
+
+// Allocate a file and load a file from the pack archive inside.
+// The data pointed by the pointer in the output need to be freed once is not needed anymore.
+// pack_id: pack file identifier
+// file_index: file index
+// output: [output] result struct (will contain length and pointer)
+// malloc_flags: allocation flags
 void AllocAndLoadFileInPack(enum pack_file_id pack_id, u32 file_index, struct pack_alloc_and_load_result *output, u32 malloc_flags);
-void OpenPackFile(struct pack_file_opened *pack_file,char *file_path);
+
+// Open a Pack file, to be read later. Initialise the output structure.
+// pack_file: [output] pack file struct
+// file_path: file name
+void OpenPackFile(struct pack_file_opened *pack_file, char *file_path);
+
+// Get the length of a file entry from a Pack archive
+// pack_file: pack file struct
+// file_index: file index
+// return: size of the file in bytes from the Pack Table of Content
 u32 GetFileLengthInPack(struct pack_file_opened* pack_file, u32 file_index);
-u32 LoadFileInPack(struct pack_file_opened *pack_file,void *output_buffer,u32 file_index);
+
+// Load the indexed file from the Pack archive, itself loaded from the ROM.
+// pack_file: pack file struct
+// output_buffer: [output] target buffer
+// file_index: file index
+// return: number of read bytes (identical to the length of the pack from the Table of Content)
+u32 LoadFileInPack(struct pack_file_opened *pack_file, void *output_buffer,u32 file_index);
 
 #endif //PMDSKY_MAIN_PACK_H

include/overlay_29_022E0354.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022E0354(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022E0354_H

include/overlay_29_022E1A1C.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022E1A1C(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022E1A1C_H

include/overlay_29_022E32E8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022E32E8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022E32E8_H

include/overlay_29_022E37B8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022E37B8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022E37B8_H

include/overlay_29_022E95F4.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022E95F4(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022E95F4_H

include/overlay_29_022EC608.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022EC608(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022EC608_H

include/overlay_29_022ECDC0.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022ECDC0(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022ECDC0_H

include/overlay_29_022EE348.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022EE348(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022EE348_H

include/overlay_29_022EF7A0.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022EF7A0(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022EF7A0_H

include/overlay_29_022F0590.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022F0590(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022F0590_H

include/overlay_29_022F528C.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022F528C(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022F528C_H

include/overlay_29_022F62A8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022F62A8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022F62A8_H

include/overlay_29_022F7364.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022F7364(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022F7364_H

include/overlay_29_022FC99C.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022FC99C(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022FC99C_H

include/overlay_29_022FED98.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__022FED98(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_022FED98_H

include/overlay_29_023000E4.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__023000E4(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_023000E4_H

include/overlay_29_02302A38.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02302A38(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02302A38_H

include/overlay_29_023047B8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__023047B8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_023047B8_H

include/overlay_29_0230558C.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0230558C(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0230558C_H

include/overlay_29_02305C04.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02305C04(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02305C04_H

include/overlay_29_02307EF8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02307EF8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02307EF8_H

include/overlay_29_0230827C.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0230827C(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0230827C_H

include/overlay_29_02308FBC.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02308FBC(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02308FBC_H

include/overlay_29_0230E8F0.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0230E8F0(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0230E8F0_H

include/overlay_29_0230F008.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0230F008(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0230F008_H

include/overlay_29_02311010.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02311010(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02311010_H

include/overlay_29_023118B4.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__023118B4(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_023118B4_H

include/overlay_29_02315118.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02315118(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02315118_H

include/overlay_29_02318D34.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02318D34(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02318D34_H

include/overlay_29_02318E4C.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02318E4C(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02318E4C_H

include/overlay_29_02319F8C.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02319F8C(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02319F8C_H

include/overlay_29_0231B194.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0231B194(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0231B194_H

include/overlay_29_0231CBC8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0231CBC8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0231CBC8_H

include/overlay_29_0231EDD8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0231EDD8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0231EDD8_H

include/overlay_29_0231F570.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0231F570(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0231F570_H

include/overlay_29_0231FBFC.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0231FBFC(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0231FBFC_H

include/overlay_29_0232017C.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0232017C(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0232017C_H

include/overlay_29_02320764.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02320764(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02320764_H

include/overlay_29_02321438.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02321438(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02321438_H

include/overlay_29_02325620.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02325620(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02325620_H

include/overlay_29_0232800C.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValidMoveEffects__0232800C(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0232800C_H

include/overlay_29_0232A3D8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValidMoveEffects__0232A3D8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0232A3D8_H

include/overlay_29_0232C500.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValidMoveEffects__0232C500(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0232C500_H

include/overlay_29_0232E250.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValidMoveEffects__0232E250(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0232E250_H

include/overlay_29_0232E840.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0232E840(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0232E840_H

include/overlay_29_02333FAC.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02333FAC(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02333FAC_H

include/overlay_29_023350D8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__023350D8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_023350D8_H

include/overlay_29_02337CA8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02337CA8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02337CA8_H

include/overlay_29_02344AF8.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02344AF8(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02344AF8_H

include/overlay_29_02345698.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02345698(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02345698_H

include/overlay_29_02347BA4.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__02347BA4(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_02347BA4_H

include/overlay_29_0234987C.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0234987C(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0234987C_H

include/overlay_29_0234DDD0.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0234DDD0(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0234DDD0_H

include/overlay_29_0234EC14.h

@@ -3,6 +3,9 @@
 
 #include "dungeon_mode.h"
 
+// Checks if an entity pointer points to a valid entity (not entity type 0, which represents no entity).
+// entity: entity pointer
+// return: bool
 u8 EntityIsValid__0234EC14(struct entity *entity);
 
 #endif //PMDSKY_OVERLAY_29_0234EC14_H