[Maintenance] Fix comment↔code associations

• Comments that describe all lines of code until a blank one are placed
  into the lines immediately above
• Comments that describe an entire demarcated block are placed
  immediately below the dash row at the top
• In any case, there should be a blank line after the top comment of
  a demarcated block, to keep IntelliSense-style systems from applying
  the block comment to the first actual line of code…
• …but there shouldn't be one before the dash row at the bottom, where
  it'd be redundant.

Part of P0207, funded by GhostPhanom.

decomp.hpp

@@ -9,6 +9,7 @@
 //	if(FLAGS_*) { goto some_label; | return; }
 // these assemble into the single given instruction. Apply the ! operator to
 // get the N versions.
+
 #define FLAGS_CARRY (_FLAGS & 0x01) /* JC / JAE / JB */
 #define FLAGS_ZERO (_FLAGS & 0x40) /* JZ */
 #define FLAGS_SIGN (_FLAGS & 0x80) /* JS */

master.hpp

@@ -31,6 +31,7 @@ struct point_t {
 
 /// Memory model definitions (adapted from master.h)
 /// ------------------------------------------------
+
 #if !defined(MASTER_NEAR) && !defined(MASTER_FAR) && !defined(MASTER_COMPACT) && !defined(MASTER_MEDIUM)
 	#if defined(__SMALL__) || defined(__TINY__) || defined(M_I86SM) || defined(M_I86TM)
 		#define MASTER_NEAR
@@ -68,6 +69,7 @@ struct point_t {
 
 /// Original functions (only contains those actually called from ZUN code)
 /// ----------------------------------------------------------------------
+
 #ifdef __cplusplus
 extern "C" {
 #endif

pc98.h

@@ -35,6 +35,7 @@ typedef unsigned int utram_kanji_amount_t;
 // Display-space coordinate, with [0; RES_X[ being the visible area.
 typedef int screen_x_t;
 typedef unsigned int uscreen_x_t;
+
 // Display-space coordinate, with [0; RES_Y[ being the visible area. Does not
 // care about 200- or 400-line graphics modes or vertical scrolling.
 typedef int screen_y_t;
@@ -42,6 +43,7 @@ typedef unsigned int uscreen_y_t;
 
 // VRAM X coordinate, ranging from 0 to (RES_X / BYTE_DOTS).
 typedef int vram_x_t;
+
 // VRAM Y coordinate, ranging from 0 to either 400 or 200 depending on the
 // current graphics mode, and with an added vertical scrolling offset.
 typedef int vram_y_t;
@@ -50,6 +52,7 @@ typedef unsigned int uvram_y_t;
 // Text RAM X coordinate, ranging from 0 to (RES_X / GLYPH_HALF_W).
 typedef int tram_x_t;
 typedef unsigned int utram_x_t;
+
 // Text RAM Y coordinate, ranging from 0 to (RES_Y / GLYPH_H).
 typedef int tram_y_t;
 typedef unsigned int utram_y_t;
@@ -152,6 +155,7 @@ typedef int8_t uint4_t;
 
 /// Memory segments
 /// ---------------
+
 #define SEG_TRAM_JIS 0xA000
 #define SEG_TRAM_ATRB 0xA200
 
@@ -162,6 +166,7 @@ typedef int8_t uint4_t;
 
 // Segment distance between B↔R↔G
 #define SEG_PLANE_DIST_BRG 0x800
+
 // Segment distance between G↔E
 #define SEG_PLANE_DIST_E 0x2800
 /// ---------------

platform.h

@@ -5,6 +5,7 @@
 
 /// <stdint.h>
 /// ----------
+
 // __TURBOC__ is #define'd on both "Borland" and "Turbo" editions, unlike
 // __BORLANDC__, which is only #define'd on the former.
 #if defined(__TURBOC__) && defined(__MSDOS__)

th01/formats/grz.h

@@ -42,6 +42,7 @@ int grx_load_noplanar(unsigned int slot, const char *fn);
 
 // Display
 // -------
+
 // Equivalent to grz_put_stream(slot, 0);
 void grx_put(unsigned int slot);
 

th01/formats/ptn.hpp

@@ -120,6 +120,7 @@ void ptn_put_8(screen_x_t left, vram_y_t top, int ptn_id);
 // like this:
 // | 0 | 1 |
 // | 2 | 3 |
+
 #define PTN_QUARTER_W 16
 #define PTN_QUARTER_H 16
 

th01/fuuin_02.cpp

@@ -27,6 +27,7 @@ extern "C" {
 
 // Input
 // -----
+
 void input_sense(bool16 reset_repeat)
 {
 	extern uint8_t input_prev[10];

th01/hardware/graph.cpp

@@ -54,6 +54,7 @@ extern page_t page_accessed;
 
 /// Clipping
 /// --------
+
 #define fix_order(tmp, low, high) \
 	if(low > high) { \
 		tmp = low; \
@@ -88,6 +89,7 @@ extern page_t page_accessed;
 
 /// BIOS
 /// ----
+
 inline void graph_access_and_show_0() {
 	graph_accesspage_func(0);
 	graph_showpage_func(0);
@@ -160,6 +162,7 @@ void z_graph_hide()
 
 /// Page flipping
 /// -------------
+
 void graph_showpage_func(page_t page)
 {
 	outportb(0xA4, page);
@@ -174,6 +177,7 @@ void graph_accesspage_func(int page)
 
 /// Hardware
 /// --------
+
 void z_palette_show_single(int col, int r, int g, int b)
 {
 	outportb(0xA8, col);
@@ -391,6 +395,7 @@ int z_graph_readdot(screen_x_t x, vram_y_t y)
 
 /// Restorable line drawing
 /// -----------------------
+
 // Never read from, so it's supposedly only there for debugging purposes?
 extern screen_point_t graph_r_last_line_end;
 // `true` copies the pixels to be drawn from the same position on page 1, thus
@@ -923,6 +928,7 @@ struct respal_t {
 // Memory Control Block
 // Adapted from FreeDOS' kernel/hdr/mcb.h
 // --------------------
+
 #define MCB_NORMAL 0x4d
 #define MCB_LAST   0x5a
 

th01/hardware/graph.h

@@ -1,5 +1,6 @@
 /// BIOS
 /// ----
+
 // Enables the graphics layer in 640x400 mode, applies z_Palettes, and clears
 // page 0.
 void z_graph_init(void);
@@ -12,6 +13,7 @@ void z_graph_hide(void);
 
 /// Pages
 /// -----
+
 void graph_showpage_func(page_t page);
 void graph_accesspage_func(int page);
 
@@ -29,6 +31,7 @@ void graph_copy_accessed_page_to_other(void);
 
 /// GRCG
 /// ----
+
 void grcg_setcolor_rmw(int col);
 
 // Enters TCR (Tile Compare Read / "color extraction") mode. VRAM reads will
@@ -47,6 +50,7 @@ void z_grcg_boxfill(
 
 /// Points
 /// ------
+
 void z_grcg_pset(screen_x_t x, vram_y_t y, int col);
 // Returns the color value at the given point on the current VRAM page.
 int z_graph_readdot(screen_x_t x, vram_y_t y);
@@ -54,8 +58,11 @@ int z_graph_readdot(screen_x_t x, vram_y_t y);
 
 /// Restorable line drawing
 /// -----------------------
-// Draws straight horizontal or vertical lines.
+
+// Draws straight horizontal lines.
 void graph_r_hline(screen_x_t left, screen_x_t right, vram_y_t y, int col);
+
+// Draws straight vertical lines.
 void graph_r_vline(screen_x_t x, vram_y_t top, vram_y_t bottom, int col);
 
 // Draws a line with an arbitrary angle between the two points.
@@ -105,6 +112,7 @@ void graph_r_lineloop_unput(
 
 /// Text
 /// ----
+
 // Calculates the width of [str], displayed with the given [fx].
 int text_extent_fx(int fx, const unsigned char *str);
 
@@ -124,6 +132,7 @@ void graph_putfwnum_fx(
 
 /// Blitting
 /// --------
+
 // Copies the given rectangle on the current from
 //     (⌊left/8⌋*8, top)
 // to

th01/hardware/input.hpp

@@ -6,6 +6,7 @@ extern bool input_ok;
 
 // REIIDEN.EXE and FUUIN.EXE
 // -------------------------
+
 // Hey, at least two inputs merged into a single variable! It's a start.
 enum input_lr_t {
 	INPUT_NONE = 0,

th01/hardware/palette.h

@@ -103,6 +103,7 @@ void z_palette_white_out(void);
 
 /// Resident palette
 /// ----------------
+
 // Copies the resident palette to z_Palettes and sets all hardware colors.
 // Returns 1 on success, 0 on failure.
 int z_respal_get_show(void);

th01/hardware/ztext.h

@@ -1,5 +1,6 @@
 // master.lib text function reimplementations
 // ------------------------------------------
+
 typedef enum {
 	CURSOR_HIDE,
 	CURSOR_BLOCK,

th01/hiscore/regist.cpp

@@ -62,6 +62,7 @@ extern screen_y_t entered_name_top;
 
 /// Alphabet
 /// --------
+
 #define ALPHABET_TOP 240
 #define MARGIN_W 32
 #define KANJI_PADDING_X 16

th01/main/boss/entity_a.cpp

@@ -61,6 +61,7 @@ struct bos_t {
 
 /// Entities
 /// --------
+
 extern bos_t bos_entity_images[BOS_ENTITY_SLOT_COUNT];
 extern bool bos_header_only;
 
@@ -116,6 +117,7 @@ void CBossEntity::metadata_get(
 
 /// Blitting
 /// --------
+
 void CBossEntity::put_8(screen_x_t left, vram_y_t top, int image) const
 {
 	vram_offset_t vram_offset_row = vram_offset_divmul(left, top);
@@ -609,6 +611,7 @@ void bos_entity_free(int slot)
 
 /// Non-entity animations
 /// ---------------------
+
 extern bos_t bos_anim_images[BOS_ANIM_SLOT_COUNT];
 
 int CBossAnim::load(const char fn[PF_FN_LEN], int slot)

th01/main/bullet/pellet.cpp

@@ -2,6 +2,7 @@
 
 /// Constants
 /// ---------
+
 // Can't declare these as `static const` variables, because that would break
 // compile-time Subpixel arithmetic
 #define PELLET_LEFT_MIN (PLAYFIELD_LEFT)

th01/main/debug.hpp

@@ -6,6 +6,7 @@ extern bool16 test_damage;
 
 /// Memory info screen
 /// ------------------
+
 // Hides the graphics layer and enters a memory usage screen with some debug
 // options, in a blocking way. Set [input_mem_leave] to `true` to return to
 // the game.

th01/main/hud/hud.cpp

@@ -63,6 +63,7 @@ static const pixel_t SCORE_AND_CARDCOMBO_W = (CARDCOMBO_RIGHT - SCORE_LEFT);
 
 /// Globals
 /// -------
+
 // Forces re-rendering of all full-width numbers on the HUD, even if they
 // haven't changed since the last render call.
 extern bool fwnum_force_rerender;
@@ -75,6 +76,7 @@ extern unsigned char hud_cardcombo_max; // Why a separate variable???
 
 /// Functions
 /// ---------
+
 inline screen_x_t col_left(screen_x_t first_left, int col) {
 	return (first_left + (col * COL_W));
 }

th01/main/hud/hud.hpp

@@ -27,6 +27,7 @@ void hud_lives_put(int prev);
 void hud_bombs_put(int prev);
 
 /// Background
+
 /// ----------
 // Loads the first plane from the .GRF file with the given [fn] into [hud_bg],
 // and sets [hud_bg_size] to its size in bytes. Always returns 0.

th01/main/player/orb.cpp

@@ -11,6 +11,7 @@ inline double gravity_for(const double& force) {
 }
 /// Temporary data segment workarounds
 /// ----------------------------------
+
 // Also needs to be spelled out in ASM to avoid the unwanted WAIT instruction
 // afterwards.
 #define GRAVITY_FOR(force) \

th01/main/player/player.cpp

@@ -974,6 +974,7 @@ void player_miss_animate_and_update(void)
 
 	// Miss sprite and shake
 	// ---------------------
+
 	// ZUN bug: This should have been the 48×48 unblitting call that's done
 	// after the shake. It's easily possible to get hit during an 48×48
 	// animation, which will end up leaving the extra pixels on screen during

th01/main/stage/stageobj.hpp

@@ -161,6 +161,7 @@ void stageobjs_init_and_render(int stage_id);
 
 // Blitting
 // --------
+
 // Stationary stage objects are blitted to both VRAM pages, which makes it
 // possible to efficiently unblit the other entities moving on top of them, by
 // simply restoring pixels from VRAM page 1. Since the player can remove
@@ -171,12 +172,13 @@ void stageobjs_init_and_render(int stage_id);
 // Since obstacles also need to be removed during a stage transition, their
 // backgrounds are stored as well. This makes absolutely sure that a .GRP only
 // needs to be blitted a single time, when entering a new scene.
-
+//
 // Planar<ptn_plane_t> would have been enough though, since there's no alpha
 // plane to be snapped from VRAM anyway... Assumed by everything to contain
 // [card_count] card backgrounds first, followed by [obstacle_count] obstacle
 // backgrounds.
 extern ptn_t *stageobj_bgs;
+
 extern unsigned long stageobj_bgs_size;
 
 // Frees any previously allocated [stageobj_bgs]. Always returns 0.

th01/math/overlap.hpp

@@ -1,4 +1,6 @@
-// Generic overlap testing macros for collision detection.
+// Generic overlap testing macros for collision detection
+// ------------------------------------------------------
+
 #define overlap_xywh_xywh_lt_gt(x1, y1, w1, h1, x2, y2, w2, h2) ( \
 	(((x1) - (x2)) < (w2)) && \
 	(((x1) - (x2)) > -(w1)) && \

th02/core/zunerror.h

@@ -1,7 +1,6 @@
 // Debugging
 // ---------
-// Calls ZUN's interrupt vector set up in ZUNINIT.COM to display an error
-// message.
+
 typedef enum {
 	ERROR_FILE_NOT_FOUND = 2,
 	ERROR_OUT_OF_MEMORY = 3,
@@ -11,5 +10,7 @@ typedef enum {
 	_zun_error_t_FORCE_UINT16 = 0xFFFF
 } zun_error_t;
 
+// Calls ZUN's interrupt vector set up in ZUNINIT.COM to display an error
+// message.
 void pascal zun_error(zun_error_t err);
 // ---------

th03/formats/cdg.h

@@ -58,6 +58,7 @@ extern CDG cdg_slots[CDG_SLOT_COUNT];
 
 // Loading and freeing
 // -------------------
+
 // Loads all images of the CDG file [fn], starting at [slot_first] and
 // incrementing the slot number for every further image.
 void pascal cdg_load_all(int slot_first, const char *fn);
@@ -80,6 +81,7 @@ void pascal cdg_free_all(void);
 
 // Blitting
 // --------
+
 // Displays the CDG image in the given [slot] at (⌊left/8⌋*8, top).
 void pascal cdg_put_8(screen_x_t left, vram_y_t top, int slot);
 

th03/hardware/input.h

@@ -18,6 +18,7 @@ static const input_t INPUT_Q          = 0x4000;
 
 /// Variables
 /// ---------
+
 // Multi-player P1/P2 controls
 extern input_t input_mp_p1;
 extern input_t input_mp_p2;

th03/main/player/combo.h

@@ -24,6 +24,7 @@ void combo_update_and_render(void);
 
 /// Hit combo slots
 /// ---------------
+
 // Number of simultaneous, separate hit combos tracked per player. *Not*
 // related to the number of explosions on screen; rather, each explosion is
 // assigned one of these slots when it spawns. All consecutive explosions

th03/main/player/player.hpp

@@ -11,6 +11,7 @@
 
 // Gauge
 // -----
+
 #define GAUGE_MAX (0xFF << 4)
 
 typedef uint16_t gauge_t;
@@ -21,6 +22,7 @@ void pascal near gauge_avail_add(unsigned char pid, unsigned char charge);
 
 // Charge Shots
 // ------------
+
 typedef void (far pascal *near chargeshot_add_func_t)(
 	Subpixel center_x, Subpixel center_y
 );

th03/op_01.cpp

@@ -21,6 +21,7 @@ bool snd_sel_disabled = false; // Yes, it's just (!snd_fm_possible).
 
 /// YUME.CFG loading and saving
 /// ---------------------------
+
 // These will be removed once the strings can be defined here
 #undef CFG_FN
 extern const char CFG_FN[];

th04/formats/bb.h

@@ -23,6 +23,7 @@ void pascal near bb_boss_load(const char far *fn);
 
 /// Text dissolve circles
 /// ---------------------
+
 #define BB_TXT_W 32
 #define BB_TXT_H 32
 #define BB_TXT_VRAM_W (BB_TXT_W / BYTE_DOTS)

th04/formats/scoredat.h

@@ -103,5 +103,4 @@ extern scoredat_section_t hi2;
 	void near scoredat_load_for_cur(void);
 #endif
 // -------
-
 /// ---------

th04/main/bullet/bullet.hpp

@@ -5,6 +5,7 @@
 
 /// Game-specific group and spawn types
 /// -----------------------------------
+
 #if GAME == 5
 	#include "th05/main/bullet/types.h"
 #else
@@ -14,6 +15,7 @@
 
 /// States and modes
 /// ----------------
+
 static const int BMS_DECAY_FRAMES_PER_CEL = 4;
 #define BSS_CLOUD_FRAMES (BULLET_CLOUD_CELS * 4)
 #define BMS_DECAY_FRAMES (BULLET_DECAY_CELS * BMS_DECAY_FRAMES_PER_CEL)
@@ -31,6 +33,7 @@ static const int BMS_DECAY_FRAMES_PER_CEL = 4;
 enum bullet_spawn_state_t {
 	/// Hitbox is active
 	/// ----------------
+
 	BSS_GRAZEABLE = 0,
 	BSS_GRAZED = 1,
 	BSS_ACTIVE = 2,
@@ -38,6 +41,7 @@ enum bullet_spawn_state_t {
 
 	/// Delay "cloud", no hitbox
 	/// ------------------------
+
 	BSS_CLOUD_BACKWARDS = 3,
 	BSS_CLOUD_FORWARDS = 4,
 	BSS_CLOUD_END = (BSS_CLOUD_FORWARDS + BSS_CLOUD_FRAMES),
@@ -49,6 +53,7 @@ enum bullet_spawn_state_t {
 enum bullet_move_state_t {
 	/// Hitbox is active
 	/// ----------------
+
 	// Slows down from BMS_SLOWDOWN_BASE_SPEED to [final_speed]
 	BMS_SLOWDOWN = 0,
 	// Special processing according to [special_motion]
@@ -59,6 +64,7 @@ enum bullet_move_state_t {
 
 	/// Decay, no hitbox
 	/// ----------------
+
 	BMS_DECAY = 4,
 	BMS_DECAY_END = (BMS_DECAY + BMS_DECAY_FRAMES),
 	/// ----------------
@@ -206,6 +212,7 @@ extern union {
 
 /// Template
 /// --------
+
 struct BulletTemplate {
 	uint8_t spawn_type;
 	unsigned char patnum;	// TH05: 0 = pellet
@@ -261,6 +268,7 @@ struct BulletTemplate {
 };
 
 extern BulletTemplate bullet_template;
+
 // Separate from the template, for some reason?
 extern bullet_special_angle_t bullet_template_special_angle;
 

th04/main/circle.hpp

@@ -1,5 +1,6 @@
 // Growing or shrinking circles
 // ----------------------------
+
 // [center_x] and [center_y] are *passed* as subpixels, but stored at pixel
 // precision, as master.lib's grcg_circle() function doesn't support more than
 // that anyway.

th04/main/hud/hud.hpp

@@ -2,6 +2,7 @@
 
 // Low-level
 // ---------
+
 // Renders the "Enemy!!" caption and the HP bar, showing the given [bar_value]
 // between 0 and BAR_MAX.
 void pascal hud_hp_put(int bar_value);

th04/main/item/item.hpp

@@ -64,6 +64,7 @@ void pascal near items_miss_add(void);
 
 // Collection counters
 // -------------------
+
 // Reset to 0 when moving to a new stage.
 extern unsigned int stage_point_items_collected;
 
@@ -77,6 +78,7 @@ extern unsigned int items_collected;
 #endif
 
 extern unsigned int total_point_items_collected;
+
 // TH04 includes items collected above the PoC during a bomb, TH05 doesn't.
 extern unsigned int total_max_valued_point_items_collected;
 // -------------------

th04/main/player/bomb.hpp

@@ -9,6 +9,7 @@ extern unsigned char bomb_frame;
 
 // Character-specific bomb update and render functions
 // ---------------------------------------------------
+
 extern nearfunc_t_near playchar_bomb_func;
 
 void pascal near bomb_reimu(void);

th04/main/pointnum/pointnum.hpp

@@ -69,6 +69,7 @@ void pascal near pointnums_update(void);
 
 /// Rendering
 /// ---------
+
 // Stores pointers to all point numbers that should be rendered in the current
 // frame. Starts with the white ones, and [pointnum_first_yellow_alive]
 // indicates the first yellow one.

th04/main/tile/tile.hpp

@@ -26,6 +26,7 @@ void pascal near tiles_render_all(void);
 
 /// Redraw
 /// ------
+
 // Subdivides each 16×16 tile into two 16×8 halves and marks whether that half
 // should be redrawn by the next call to tiles_redraw_invalidated() if its
 // entry is nonzero.

th05/main/boss/bosses.hpp

@@ -65,6 +65,7 @@ BOSS_DEC(louise);
 BOSS_DEC(alice);
 
 BOSS_DEC(mai_yuki);
+
 // Pointing to the same address as [boss2]! Might not be possible anymore once
 // that variable has to be moved to a C++ translation unit...
 extern boss_stuff_t yuki;

th05/main/bullet/types.h

@@ -1,5 +1,6 @@
 /// Group type components
 /// ---------------------
+
 // 0° angle definition, relative to the bullet origin.
 #define BGC0_STATIC 0	/* 0° = right */
 #define BGC0_AIMED  1	/* 0° = current player position */
@@ -46,9 +47,11 @@ typedef enum {
 
 /// Spawn types
 /// -----------
+
 // Spawns special-moving bullets with BST_NORMAL after the gather animation.
 // Effectively becomes BST_NORMAL when used outside a gather_t.
 #define BST_GATHER_NORMAL_SPECIAL_MOVE 0xFE
+
 // Won't spawn bullets at the end of a gather animation.
 #define BST_GATHER_ONLY 0xFF
 

th05/main/player/shot.hpp

@@ -63,7 +63,6 @@ struct ShotAddIterator {
 	if(cycle & secondary_cycle) { \
 		sai.secondary_offset_expr; \
 	}
-// -----
 
 // We *really* want to fit those on a line...
 #define OPT_L shot->from_option_l()

th05/maine011.cpp

@@ -11,6 +11,7 @@
 /// -------------------
 /// Used to automatically change the text color whenever a specific
 /// Shift-JIS code point is encountered.
+
 static const int COLMAP_COUNT = 8;
 
 typedef struct {

th05/staff.cpp

@@ -32,6 +32,7 @@ typedef enum {
 
 // Particle structure
 // ------------------
+
 // Below this [phase_value.radius], the orb is rendered as a monochrome filled
 // circle.
 static const pixel_t ORB_RADIUS_FULL = 16;