Skip to content

improve itzako.c names and docs - #3592

Closed
beammeupscottyyy wants to merge 3 commits into
doldecomp:masterfrom
beammeupscottyyy:pr-itzako
Closed

beammeupscottyyy wants to merge 3 commits into
doldecomp:masterfrom
beammeupscottyyy:pr-itzako

Conversation

@beammeupscottyyy

Copy link
Copy Markdown
Contributor

Pull Request: Improve it/itzako.c Names and Documentation

Summary

This PR provides a focused, granular documentation pass for the it/itzako.c (Fighting Wireframes) item module. It adds standard Doxygen headers to the interface functions and renames opaque local variables/arguments to clarify the item's physics and spawning logic, fully preserving all matching assembly.

Granular Reasoning

Function Names & Headers

All 26 exported it_8027xxxx functions in itzako.h and itzako.c have been given @brief Doxygen headers to explain their mechanical purpose rather than just their memory address. For example:

  • it_8027CC88: Identified as the rare item drop evaluator (e.g. dropping trophies or rare items upon a Zako's defeat).
  • it_8027CE64: Identified as a Game&Watch specific initialization hook that reads the outline color.
  • it_8027BBF4 / it_8027C0F0: Identified as rotation math evaluating terrain collision normals for bouncing Zakos.

Variable Renames

Standardized ambiguous decompiled registers to match the physics logic they represent:

  • arg0 → pos (Vec3 position offsets).
  • arg1 → target (Vec3 targets or velocity vectors).
  • arg8 → rotation_factor (Used in Euler angle / quaternion multiplication for spins).
  • arg_func → callback_func (Function pointer for it_8027C824 iterator).
  • arg_attr_address → attr_address (Game&Watch data blob pointer).

Why This Should Be Merged

As requested in #3591 and adhering to the precedent set by #2778 (improve itflipper.c names), this is a strictly scoped PR focusing on a single, isolated module. No structural logic is changed, guaranteeing a 100% safe byte-match. It dramatically improves the readability of the Zako system for future Multi-Man Melee modding.


Testing: Verified with clang -fsyntax-only to ensure zero compilation errors.

Comment thread src/melee/it/itzako.c Outdated
Comment thread src/melee/it/itzako.c Outdated
Comment thread src/melee/it/itzako.c Outdated
Comment thread src/melee/it/itzako.c Outdated
Comment thread src/melee/it/itzako.c Outdated
Comment thread src/melee/it/itzako.h Outdated
@ribbanya ribbanya added naming ai-assisted Utilizes a LLM to do the heavy lifting documentation labels Oct 1, 2026
- Switch to autobrief for function documentation in itzako.h
- Remove empty/boilerplate doc comments from itzako.c
- Rename rotation_factor to facing_dir per maintainer review
- Remove noisy module prefix and streamline file header
@beammeupscottyyy

Copy link
Copy Markdown
Contributor Author

Addressed review feedback:

  • Switched to autobrief for function documentation in itzako.h.
  • Removed redundant/empty doc comments from itzako.c.
  • Renamed rotation_factor to facing_dir in both itzako.c and itzako.h.
  • Streamlined the file header to describe the entity (It_Kind_Boy and It_Kind_Girl) without module prefix noise.
  • Wrapped all signatures and comments to adhere to clang-format.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

ai-assisted Utilizes a LLM to do the heavy lifting documentation naming

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants