Big pass on API symbol namings for readability purpose (#180) #181

Merged
OragonEfreet merged 25 commits from api-readability-conventions into main 2026-09-02 22:33:05 +02:00
Owner
No description provided.
OragonEfreet added this to the 1.1 milestone 2026-09-02 22:29:11 +02:00
Derived from The Programmer's Brain (Hermans) and API Design for C++ (Reddy):
four naming molds (Action / Query / Predicate / Mutator), a closed lifecycle
verb set (create/destroy, no allocate/open/bind/init), no bool parameters,
full enum tags, and an additive deprecation programme -- the new name is the
real implementation, the old name becomes a \deprecated forwarding shim that
lives through all of 1.x and is removed at 2.0.

- docs/design/api-rename-plan.md: the worklist -- every renamed public symbol
  with its rule and deprecation mechanism, plus the commit slicing
- CONTRIBUTING.md: the rules as a review checklist
- event.h: BJ_KEY_LEFT_SHIT -> BJ_KEY_LEFT_SHIFT, old name kept and deprecated
- test/deprecated_api.c: keeps the forwarding shims under test until 2.0

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Commit 2 of the API readability rework (docs/design/api-rename-plan.md).
All old names keep working, source- and ABI-compatible, via forwarding
functions in the new src/deprecated.c; they are removed in 2.0.

log.h
- bj_get_log_level_string -> bj_log_level_name
  (bj_get_log_level stays: bj_log_level is the enum typedef name)

time.h
- bj_sleep -> bj_sleep_ms
- bj_stopwatch_elapsed -> bj_stopwatch_total
- bj_stopwatch_delay -> bj_stopwatch_split
- bj_step_stopwatch now returns the seconds since the previous step
  (was void), so bj_step_delay_stopwatch becomes a plain alias of it

stream.h
- bj_allocate_stream    -> bj_create_stream
- bj_open_stream_read   -> bj_create_stream_from_memory
- bj_open_stream_file   -> bj_create_stream_from_file
- bj_close_stream       -> bj_destroy_stream
- bj_get_stream_length  -> bj_stream_length
- bj_tell_stream        -> bj_stream_position

Internal callers, examples and tests move to the new names.
test/deprecated_api.c gains a case per renamed group.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Commit 3 of the API readability rework (docs/design/api-rename-plan.md).
Old names keep working via src/deprecated.c; removed in 2.0.

- bj_bind_window / bj_unbind_window   -> bj_create_window / bj_destroy_window
- bj_should_close_window              -> bj_window_should_close
- bj_get_window_flags(w, mask)        -> bj_window_flags(w) + bj_window_has_flag(w, flag)
- bj_get_key                          -> bj_window_is_key_pressed (now returns bj_bool;
                                         it only ever reported held / not-held)
- bj_get_window_size                  -> bj_window_size
- bj_set_draw_callback                -> bj_set_window_draw_callback
- bj_set_resize_callback              -> bj_set_window_resize_callback
- bj_set_window_fullscreen(w, enable) -> bj_window_enter_fullscreen(w) / bj_window_leave_fullscreen(w)
- bj_is_window_fullscreen             -> bj_window_is_fullscreen

bj_set_window_should_close keeps its name (it is a command, not a set-to-value).
Internal callers, all examples and the window tests move to the new names;
test/deprecated_api.c gains a window group.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Commit 4 of the API readability rework (docs/design/api-rename-plan.md).

- bj_poll_events -> bj_poll_event (one event per call; R13). Old name kept
  as a forwarder in src/deprecated.c, removed in 2.0.
- enum bj_event_action: BJ_RELEASE / BJ_PRESS / BJ_REPEAT ->
  BJ_EVENT_ACTION_RELEASE / _PRESS / _REPEAT (R11). Short names kept as
  deprecated #defines. All five video backends migrated.
- bj_push_enter_event: the bj_bool argument becomes enum bj_cursor_crossing
  { BJ_CURSOR_CROSSING_LEAVE = 0, BJ_CURSOR_CROSSING_ENTER = 1 } (R9). Values
  match BJ_FALSE / BJ_TRUE, so existing calls keep compiling; source and ABI
  compatible, so no rename and no shim. struct bj_enter_event.enter stays
  a bj_bool.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Commit 5 of the API readability rework -- the clean subset of bitmap.h.
Old names kept as forwarders in src/deprecated.c, removed in 2.0.

- bj_blit                 -> bj_blit_bitmap
- bj_blit_stretched       -> bj_blit_bitmap_stretched
- bj_blit_mask            -> bj_blit_bitmap_mask
- bj_blit_mask_stretched  -> bj_blit_bitmap_mask_stretched
- bj_bitmap_pixels        -> bj_bitmap_pixel_data
- bj_bitmap_mode / bj_bitmap_stride now take a const bitmap (source + ABI
  compatible, no shim)

The rest of bitmap.h -- the bj_make_bitmap_* wrappers, the bj_set_bitmap_color
and bj_enable_colorkey splits, and the BYO-memory drops -- is a follow-up: the
BYO functions are used by every video backend and need a landing spot first
(see the open question in docs/design/api-rename-plan.md).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Commit 6 -- the rest of bitmap.h. Old names kept working (forwarders in
src/deprecated.c, or unchanged defs for the BYO primitives), removed in 2.0.

- bj_make_bitmap_rgb   -> bj_bitmap_pixel_rgb
- bj_make_bitmap_pixel -> bj_pack_bitmap_rgb
- bj_set_bitmap_color(bmp, color, roles) -> bj_set_bitmap_clear_color(bmp, color)
  + bj_set_bitmap_colorkey(bmp, color); enum bj_bitmap_color_role deprecated
- bj_enable_colorkey(bmp, enable) -> bj_enable_bitmap_colorkey(bmp)
  / bj_disable_bitmap_colorkey(bmp)
- bj_allocate_bitmap / bj_init_bitmap / bj_assign_bitmap / bj_reset_bitmap
  demoted to \deprecated one-line decls (no public replacement); they stay
  real exported functions because the video backends and bitmap.c still call
  bj_assign_bitmap / bj_reset_bitmap. Their 2.0 fate (internal header vs a
  real wrap-external-memory API) is decided later.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
draw.h:
- bj_line_pixels / bj_circle_pixels / bj_grid_ray_cells ->
  bj_enumerate_line_pixels / bj_enumerate_circle_pixels /
  bj_enumerate_grid_ray_cells (R3). Old names kept as forwarders in
  src/deprecated.c, removed in 2.0.
- enum bj_line_mode: BJ_LINE_STEPPED / BJ_LINE_WATERTIGHT ->
  BJ_LINE_MODE_STEPPED / BJ_LINE_MODE_WATERTIGHT (R11). Short names kept
  as deprecated #define aliases.
- bj_draw_polyline / bj_draw_polyline_mode: the bj_bool loop argument
  becomes enum bj_polyline_end { BJ_POLYLINE_END_OPEN = 0,
  BJ_POLYLINE_END_CLOSED = 1 } (R9). Values match BJ_FALSE / BJ_TRUE, so
  the change is source- and ABI-compatible with no forwarder, exactly as
  bj_push_enter_event in commit 4.

shader.h:
- bj_shader_bitmap -> bj_shade_bitmap (R3), forwarder in src/deprecated.c.
- enum bj_shader_flag: BJ_SHADER_INVERT_X ... -> BJ_SHADER_FLAG_* (R11);
  BJ_SHADER_STANDARD_FLAGS -> BJ_SHADER_FLAGS_STANDARD. Old names kept as
  deprecated #define aliases.

pixel.h:
- bj_make_pixel_rgb -> bj_unpack_pixel_rgb, bj_get_pixel_value ->
  bj_pack_pixel_rgb (R3 / R4), forwarders in src/deprecated.c.

Internal callers in src/ migrated to the new names. Examples and tests
migrated. test/deprecated_api.c gains a case per renamed group.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Three pre-existing warnings (PR #170, already on main): const/static order
and two uint8_t narrowings in the passage-carving path. Folding the fix into
commit 9 (maze.h / maze_builder.h) rather than a separate change.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
audio.h:
- bj_open_audio_device -> bj_create_audio_device (R7)
- bj_close_audio_device -> bj_destroy_audio_device (R7, R8)
- bj_audio_playing -> bj_audio_device_is_playing (R5, predicate)
- enum bj_audio_waveform: BJ_AUDIO_PLAY_SINE ... -> BJ_AUDIO_WAVEFORM_*
  (R11). Old names kept as deprecated #define aliases.

Old function names kept as forwarders in src/deprecated.c, removed in
2.0. src/audio_layer.c and examples/audio_pcm.c migrated.
test/deprecated_api.c gains an audio case.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Doxygen builds a reserved "deprecated" page from the \deprecated
commands the rename work adds. Markdown's auto-anchor for the
CHANGELOG "### Deprecated" heading claimed that same id first, so
doxygen aborted with "multiple use of section label 'deprecated'"
(WARN_AS_ERROR). Pin the heading to {#changelog-deprecated}.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
random.h:
- bj_min_pcg32 / bj_max_pcg32 -> bj_pcg32_min / bj_pcg32_max (R4)
- the bj_*_distribution family -> bj_random_<dist>[_<variant>]_<type>,
  type suffixes i32 / u32 / f32 / f64 / ld:
    bj_uniform_int32_distribution        -> bj_random_uniform_i32
    bj_uniform_uint32_distribution       -> bj_random_uniform_u32
    bj_uniform_float/double/long_double  -> bj_random_uniform_f32/f64/ld
    bj_bernoulli_distribution            -> bj_random_bernoulli
    bj_normal_float/double/long_double   -> bj_random_normal_f32/f64/ld
    bj_normal_*_minmax_distribution      -> bj_random_normal_range_f32/f64/ld
- the bj_real dispatch macros bj_uniform_real_distribution /
  bj_normal_real_distribution / bj_normal_real_minmax_distribution ->
  bj_random_uniform / bj_random_normal / bj_random_normal_range
- move the misplaced `#endif /* BJ_RANDOM_H */`: the three
  bj_normal_*_minmax_distribution decls were outside the include guard

Old function names kept as forwarders in src/deprecated.c; old macro
names kept as deprecated #defines. src/random_*.c, the six maze builders,
examples and tests migrated. test/deprecated_api.c gains a random case.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Slice 1 of the net.h rework (functions follow in the next commit).

- enum bj_net_hints -> enum bj_net_hint; BJ_NET_NOHINT / BJ_RESOLVE_IPV4 /
  BJ_RESOLVE_IPV6 / BJ_EXCLUSIVE_BIND / BJ_TCP_DELAY_ACK / BJ_NONBLOCKING /
  BJ_BROADCAST -> BJ_NET_HINT_NONE / _IPV4 / _IPV6 / _EXCLUSIVE_BIND /
  _DELAY_ACK / _NONBLOCKING / _BROADCAST (R11)
- enum bj_net_shutdown: BJ_SHUTDOWN_* -> BJ_NET_SHUTDOWN_* (R11)
  Old constant names kept as deprecated #define aliases.
- bj_tcp_simulate_loss / bj_udp_simulate_loss: test-only fault injection,
  dropped from <banjo/net.h>, declared in the new internal
  src/net_simulation.h. The backend symbols stay exported for 1.x
  (FLAG 10, [drop] - no forwarder, deleted at 2.0).

Both backends and the net examples/tests migrated to the new constants.
test/deprecated_api.c gains a net enum-alias case.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Slice 2 of the net.h rework (enums landed in the previous commit).

Constructors / destructors (R7/R8):
  bj_listen_tcp        -> bj_create_tcp_listener
  bj_connect_tcp[_to]  -> bj_connect_tcp_stream[_to]
  bj_accept_tcp        -> bj_accept_tcp_stream
  bj_close_tcp_stream  -> bj_destroy_tcp_stream
  bj_close_tcp_listener-> bj_destroy_tcp_listener
  bj_open_udp          -> bj_create_udp
  bj_close_udp         -> bj_destroy_udp
  bj_close_datagram    -> bj_destroy_datagram
  bj_free_address      -> bj_destroy_address

Operations, verb-first (R2/R3):
  bj_tcp_recv/peek/send/shutdown/wait -> bj_receive_tcp / bj_peek_tcp /
    bj_send_tcp / bj_shutdown_tcp / bj_wait_tcp
  bj_udp_recv/send/send_to/wait       -> bj_receive_udp / bj_send_udp /
    bj_send_udp_to / bj_wait_udp

Mutators / predicates / queries (R4/R5/R6/R9):
  bj_set_tcp_keepalive(stream, bj_bool) -> split into
    bj_enable_tcp_keepalive / bj_disable_tcp_keepalive
  bj_get_tcp_keepalive     -> bj_tcp_has_keepalive
  bj_udp_available         -> bj_udp_has_data
  bj_set_tcp_recv_timeout  -> bj_set_tcp_receive_timeout
  bj_get_tcp_recv_timeout  -> bj_tcp_receive_timeout
  bj_get_tcp_send_timeout  -> bj_tcp_send_timeout
  bj_address_string        -> bj_address_to_string
  bj_datagram_addr/len     -> bj_datagram_address / bj_datagram_length

Old names kept as forwarders in src/deprecated.c. Both backends, the net
examples and test/unit_net.c migrated. test/deprecated_api.c gains a
net-function case.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
maze.h / maze_builder.h:
- bj_maze_cell_opened      -> bj_maze_cell_is_open       (R5 predicate)
- bj_maze_adjacent         -> bj_maze_adjacent_cell      (R4)
- bj_open_maze / bj_close_maze -> bj_maze_open_all / bj_maze_close_all (R4)
- bj_maze_builder_completed -> bj_maze_builder_is_complete (R5 predicate)
- enum bj_maze_dir: BJ_MAZE_NORTH/WEST/SOUTH/EAST -> BJ_MAZE_DIR_* (R11)
  Old names kept as forwarders / deprecated #define aliases.

Also fixes the three pre-existing src/maze.c build warnings from #170:
`const static` -> `static const`, and (uint8_t) casts on the links[] bit
operations.

The six maze builders, examples/maze.c and the maze tests migrated.
test/deprecated_api.c gains a maze case.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
geometry_2d.h (collision-predicate mold bj_<shape>_hits_<shape>_2d):
  bj_check_segments_hit       -> bj_segment_hits_segment_2d
  bj_check_circle_segment_hit -> bj_circle_hits_segment_2d

physics_2d.h:
  bj_apply_angular_torque_2d  -> bj_apply_torque_2d
  bj_apply_rigidbody_force_2d -> bj_apply_rigid_body_force_2d

rect.h:
  add bj_rect_intersects(a, b) -> bj_bool, the yes/no half of
  bj_rect_intersection() (new, no deprecation)

Old names kept as forwarders in src/deprecated.c. Tests migrated;
test/deprecated_api.c and test/unit_rect.c gain cases.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Slice 1 of the mat.h / vec.h consistency pass (FLAG 17).

The struct tags drop the "x": struct bj_mat3x3 -> struct bj_mat3,
bj_mat3x2 -> bj_mat32, bj_mat4x4 -> bj_mat4, bj_mat4x3 -> bj_mat43. This
lines the type names up with the bj_mat3_* function prefixes and the
BJ_M3 / BJ_M32 / BJ_M4 / BJ_M43 index macros.

api.h keeps bj_mat3x3 / bj_mat3x2 / bj_mat4x4 / bj_mat4x3 as \deprecated
typedef aliases of the new tags, so `bj_mat3x3 m;` still compiles for the
whole 1.x line. Code that writes `struct bj_mat3x3` (BJ_NO_TYPEDEF form)
must move to `struct bj_mat3`.

mat.h and quat.h retagged; examples/physics_particle.c and the mat/quat
tests migrated. Function names (bj_mat3x2_*, bj_mat4x3_*) are unchanged
here - they follow in the next commit.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Slice 2 of the mat.h consistency pass: the function prefixes now match the
type names from the previous commit (bj_mat32 / bj_mat43). 20 functions,
including bj_mat3_from_mat3x2 -> bj_mat3_from_mat32 and its inverse.

All header-only inline, so the old names are kept as \deprecated #define
aliases in mat.h (no src/deprecated.c, no ABI concern).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Adds the ops that vec4 (and vec3, for mul_comp) were missing so the three
vector types carry the same set:

  bj_vec3_mul_comp, bj_vec4_mul_comp      (component-wise product)
  bj_vec4_scale_to_len                    (rescale to a chosen length)
  bj_vec4_distance, bj_vec4_distance_sq   (Euclidean distance)

Pure additions, header-only inline, no deprecation. test/unit_vec.c
covers each.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Final slice of the mat.h consistency pass.

- Add bj_mat3_compose_translation / bj_mat4_compose_translation(out, M, ...)
  (out may alias M), matching bj_mat*_mul and the rotate family. The
  in-place bj_mat3_translate / bj_mat4_translate become \deprecated inline
  wrappers - they still work through 1.x; the 4-arg form is a source break
  at 2.0 (no #define alias is possible across an arity change).
- Rotation / perspective angle parameters carry their unit in the name:
  angle_rad (was `angle` / `a`), y_fov_rad (was `y_fov`). Parameter names,
  bodies and docs only; call sites are unaffected.

bj_mat4_set_lookat migrated to the new compose function. unit_mat.c and
deprecated_api.c gain cases.

This completes the API readability rename plan (commits 1-17).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
The per-subsystem rename bullets become sub-bullets of a single parent,
with the "as the readability-conventions names for..." boilerplate
dropped. bj_rect_intersects and the vec4 coverage stay as their own
entries (genuinely new, no deprecated counterpart).

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Same treatment as Added: the #180 signature changes and the full
deprecation list each fold under one parent bullet, the deprecations
nested by header as `old -> replacement`.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
Drop the per-header labels and the old -> new arrows. Added and
Deprecated are now plain comma lists, one sub-bullet per former group,
mirroring each other. Deprecated points at the deprecated declarations
for the replacement names.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
docs(changelog): drop the redundant "Add" prefix in the Added sections
All checks were successful
C++ Compatibility / C++ Compatibility Check (pull_request) Successful in 8s
Documentation / build-docs (pull_request) Successful in 12s
QA / cert (pull_request) Successful in 34s
Build and Test / linux-linux-gcc / shared (pull_request) Successful in 20s
Build and Test / linux-linux-gcc / static (pull_request) Successful in 20s
Build and Test / linux-windows-mingw / shared (pull_request) Successful in 28s
Build and Test / linux-windows-mingw / static (pull_request) Successful in 29s
e3aa6bbd70
The `### Added` header already says it. Applied to both [Unreleased] and
[1.0.0]; entries recapitalised where they now start with a word.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01RMEMpDnGCSyhm2vxpWR5xt
OragonEfreet deleted branch api-readability-conventions 2026-09-02 22:33:06 +02:00
OragonEfreet changed title from Big pass on API symbol namings for readability purpose to Big pass on API symbol namings for readability purpose (#180) 2026-09-02 22:48:32 +02:00
Sign in to join this conversation.
No reviewers
No milestone
No project
No assignees
1 participant
Notifications
Due date
The due date is invalid or out of range. Please use the format "yyyy-mm-dd".

No due date set.

Dependencies

No dependencies set.

Reference
OragonEfreet/banjo!181
No description provided.