mirror of
https://github.com/doldecomp/melee.git
synced 2026-11-08 01:48:27 -10:00
itsgrimetime
4a7e914048
* Move .dox documentation inline and delete the .dox files Per the discussion in #2938, .dox files are retired: - Symbol documentation (function, struct, enum, and field blocks) now sits at the declaration: above the prototype in the header, above the static forward declaration in the C file, or on the struct field. 711 blocks were moved; the remaining unbindable ones were placed by hand. - Header copy-pasta in the .dox files (include guards, includes, and 975 undocumented prototype redeclarations) is deleted rather than moved. - The itflipper naming experiment log becomes docs/itflipper-naming.md, a Doxygen page keeping the itflipper_naming anchor its briefs reference. Directory-layout todos and two notes whose targets no longer exist are collected in docs/dox-migration-notes.md. - The @at/@sz/@szb offset and size aliases are removed from the Doxyfile and stripped from sources; offsets are already carried by the /* +NN */ comments and ASSERT_SIZE. - *.dox is dropped from the Doxyfile file patterns, the clang-format hook, and tools/functions.sh; CONTRIBUTING.md now describes the inline convention. Two prototypes gained parameter names to match their definitions and their documentation (Camera_SetBackgroundColor, Ground_801C4B50), and gm_FindGameSceneHandler's header parameter is renamed to match its definition. Doxygen output before/after: no more .dox pages (59 pages and 2512 redeclared members gone), warnings 254 -> 247, and every documented symbol with more than three words of text is still documented except the @at/@sz-only blocks. main.dol OK. * Address review: spacing around moved docs, @file placement, @dir notes - Add a blank line before every doc block this PR moved and after the declaration or field it documents. One-line trailing ///< comments are left packed, per review. - Move the eight relocated @file blocks above their include guards, merging ftcaptainspecials.h's existing one-line brief into its block. - Express the directory notes as @dir blocks in docs/dox-migration-notes.md instead of markdown headers, so they attach to the directory pages. main.dol OK; Doxygen warnings 247 -> 243.