Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/pmret/papermario/llms.txt

Use this file to discover all available pages before exploring further.

The project uses Doxygen to generate a browsable reference from comments in the source files. Writing clear Doxygen comments for matched functions and data structures makes the codebase easier to understand for everyone who comes after you. This page covers every comment style used in the project.

​
Documenting functions

Place a /// description comment directly above the function declaration or definition. Use @param to document non-obvious parameters and @return for non-obvious return values. You don’t need to document things that are self-explanatory from the name alone. 
/// Creates a foo.
void foo(void);
A fully documented function looks like this: 
/// A cool function that multiplies a number by 2.
/// @param bar the input
/// @return bar multiplied by 2
s32 foo(s32 bar) {
    return 2 * bar;
}
Rules to follow:
  • Any comments inside the function body should use the ordinary // or /* */ styles, not ///.
  • List all @param entries before @return, in the same order the parameters appear in the function signature.
  • Do not add empty @param entries for parameters whose names are self-explanatory.
  • Only add @return when the return value isn’t obvious from the function name.

​
Documenting EVT API functions

Functions that are called from EVT scripts use the @evtapi tag instead of a plain description. Document their parameters as they are passed to EVT_CALL, and do not use @return. 
/// @evtapi
/// @param SomeFlag the flag to check
void ApiFunc(void);
See include/script_api/common.h for real examples.

​
Documenting variables

Add a /// comment above a variable when its name doesn’t make its purpose completely clear, or when a set of #define values or an enum should be used with it. 
/// My description of this variable.
s32 foo;
If the variable uses a companion enum or set of defines, link to it with @see (see below).

​
Documenting files

File-level documentation goes near the top of the file, below the #include directives. Use @file followed by the file name, then a brief description of what the file covers: 
/// @file file_name.c
/// My description of this file.
Only include information that is general to the whole file — don’t repeat what individual function comments already say.

​
Documenting struct fields

Struct fields can be documented with a /// comment above the field, just like variables. If you prefer brevity, you can also use an end-of-line comment: 
typedef struct {
    /// The position in world space.
    Vec3f pos;
    s32 flags; ///< Active state flags.
} MyStruct;

​
Documenting bugs

Document a known bug on the line directly above where the buggy behaviour begins: 
/// @bug description of the bug
Use @see to link to related symbols — other functions, types, or variables that a reader should be aware of. In function comments, @see goes before the first @param: 
/// Savefile data.
/// @see SaveContext
SaveContext gSaveContext;

/// Loads a save slot.
/// @see SaveContext
/// @param slot the save slot index (0–2)
void LoadSave(s32 slot);

​
Markdown and LaTeX support

Doxygen renders Markdown inside doc comments, so you can use bold, italics, lists, and code spans freely: 
/// Processes all **active** NPCs in the current area.
/// Returns early if the NPC list is empty.
void ProcessNPCs(void);
You can also embed LaTeX for mathematical notation. Use \f$...\f$ for inline rendering and \f[...\f] for a centred block: 
/**
 * \f$ \textrm{result} = \frac{a + b}{2} \f$
 */

/**
 * \f[ \textrm{result} = \frac{a + b}{2} \f]
 */

​
Generating docs locally

To build the Doxygen HTML manual, install Doxygen and run it from the repository root: 
doxygen
The output is written to the docs/html/ directory. Open docs/html/index.html in a browser to browse the generated reference.
Doxygen must be installed separately. On Debian/Ubuntu: sudo apt install doxygen. On macOS with Homebrew: brew install doxygen.

Build docs developers (and LLMs) love

Get started for freeTalk to us