Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Add doxygen infrastructure #83

Merged
merged 1 commit into from
May 29, 2024
Merged

Add doxygen infrastructure #83

merged 1 commit into from
May 29, 2024

Conversation

malleoz
Copy link
Contributor

@malleoz malleoz commented May 13, 2024

Doxygen will be an incredible resource to have as we expand Kinoko, in terms of test cases, coverage, and collaboration. In this PR, I've left comments for most functions that I felt comfortable describing, with the hope that the rest can be filled in over time.

The following is all features I've implemented that I can think of:

  • @rename alias: Leaves a note in the documentation that the function has a poor name and should be renamed in the future
  • @unused alias: Adds [unused] in the documentation
  • @todo alias: Duh
  • The above three aliases generate unique pages when navigating to "TODO" in the nav bar.
  • @addr alias: Displays a function's address as a "qualifier" to the right of the function signature
  • @stage alias: Adds bolded text in the documentation to specify what stage of the race the function (can) run during. This may not be fully present in parts of the documentation I've added...
  • LaTeX examples - KColData::GetVertex and EGG::Quatf::dot
  • Separate Setter/Getter functions from other members in the list
    • Standardized that setters come before getters (hope this is okay)

Future improvements:

  • General HTML/CSS adjustments
  • Add Discord link to header nav bar
  • Main page besides README.md
  • Better navigation hierarchy

I'd like to establish the following precedents:

  • New functions must, at a minimum, have a brief description, as well as a @addr{0x80XXXXXX} command that maps that function to its in-game counterpart (if applicable).
  • Any new member variables must have a brief description in the header file.
  • Getter and setter functions, specifically ones which do not have an in-game counterpart and are used solely to accomodate C++ access specifiers, must be wrapped within a @beginSetters...@endSetters and @beginGetters...@endGetters.
  • Any new classes must have a brief description.

@malleoz malleoz force-pushed the doxygen branch 2 times, most recently from 4e7febd to 7dd7e16 Compare May 14, 2024 01:37
Copy link
Owner

@vabold vabold left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

host/System.cc also has ties to the base game, as KSystem is modeled loosely on RKSystem. The corresponding addresses are as follows:

KSystem::main - 80008ef0
KSystem::init - 80009194
KSystem::run - 8000951c

source/abstract/Archive.hh Outdated Show resolved Hide resolved
source/egg/core/Decomp.hh Outdated Show resolved Hide resolved
source/egg/core/Scene.cc Outdated Show resolved Hide resolved
source/egg/core/SceneManager.cc Outdated Show resolved Hide resolved
source/egg/geom/Sphere.hh Outdated Show resolved Hide resolved
source/game/system/RaceManager.cc Show resolved Hide resolved
source/game/system/RaceManager.cc Outdated Show resolved Hide resolved
source/game/system/ResourceManager.cc Outdated Show resolved Hide resolved
source/game/system/ResourceManager.cc Show resolved Hide resolved
source/game/system/Timer.hh Outdated Show resolved Hide resolved
@malleoz
Copy link
Contributor Author

malleoz commented May 28, 2024

Accounted for all of @vabold's comments above. Also applied the following changes (some may be duplicates of vabold's comments)

  • Add missing addr to EGG::Scene::~Scene
  • Move EGG::Decomp::DecodeSZS @brief to source file
  • Move EGG::Scene setter/getter bodies to source file. Group setters/getters documentation
  • Rename EGG::Matrix34f::inverseTo to inverseTo33
  • Add missing addr to EGG::Sphere3f::isInsideOtherSphere
  • Add missing addr to EGG::Vector3f::normalise as well as specifying the optional return value
  • Remove TODO comment above EGG::Vector3f::operator*(const Vector3f &rhs)
  • Add addr to singleton class headers and singleton members
    • Field::CollisionDirector
    • Field::CourseColMgr
    • Item::ItemDirector
    • Kart::KartObjectManager
    • System::CourseMap
    • System::KPadDirector
    • System::RaceConfig
    • System::RaceManager
    • System::ResourceManager
  • Add description for System::RaceManager::STAGE_COUNTDOWN_DURATION
  • Revise Kart::Hitbox header to use the @beginSetters/Getters aliases
  • Add @file for Common.hh
  • Add @brief for EGG::Mathf namespace
  • Fix malformed descriptor for EGG::Quatf::dot(const Quatf &q) by moving to source file
  • Added missing addresses to sSinCosTbl and sArcTanTbl

source/egg/math/Vector.cc Show resolved Hide resolved
source/egg/math/Vector.cc Outdated Show resolved Hide resolved
source/game/field/KColData.cc Outdated Show resolved Hide resolved
source/game/system/RaceConfig.hh Outdated Show resolved Hide resolved
source/game/system/ResourceManager.hh Outdated Show resolved Hide resolved
source/host/System.hh Outdated Show resolved Hide resolved
@malleoz
Copy link
Contributor Author

malleoz commented May 29, 2024

Updated!

@malleoz malleoz requested a review from vabold May 29, 2024 16:29
@vabold vabold merged commit 5beeae8 into vabold:main May 29, 2024
4 checks passed
@malleoz malleoz deleted the doxygen branch May 29, 2024 23:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

2 participants