Andrew Kesterson
f0858b0d38
The Doxygen comments were generated from the declarations, so 217 @throws lines across 21 headers read "When the corresponding validation or operation fails" and told a caller nothing beyond the status name. The @param lines were the same shape: every output was "Output destination populated by the function", every instance "Object to initialize, inspect, or modify". Rewritten against the implementations, following the pattern libakstdlib already uses: - @throws names the condition. akgl_sprite_load_json separated AKERR_KEY (absent) from AKERR_TYPE (present, wrong type) from AKERR_OUTOFBOUNDS (filename too long, or array indexed past its end), and gained AKGL_ERR_SDL and AKGL_ERR_HEAP, which it raises and never declared. - Parameters say whether they are required, what a NULL means, and what is written on a failure path. Where an argument is not checked, the doc says so: akgl_heap_next_actor's dest is a crash on NULL, not an error, and akgl_render_2d_frame_start dereferences self before testing it. - The conventions move up to the file blocks so the per-function docs stay short. json_helpers.h states once that absence is an error here and that json_t * results are borrowed; heap.h explains the pool model and the acquire asymmetry; physics.h carries the thrust/environmental/velocity table. - Struct fields, enum values, macros and exported globals are documented, including the dead ones - sprite_w/sprite_h, movetimer, p_scale and timer_gravity are read by nothing, and say so. Also fixes ten comments in error.h and audio.h that opened with /** rather than /**<, so Doxygen attached them to the following entity and rendered the text as part of the macro's value. Verified against the generated HTML. Comments only - no declaration changed. Doxygen builds clean under WARN_AS_ERROR, scripts/reindent.sh --check passes, 19/19 suites pass. Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
24 lines
833 B
C
24 lines
833 B
C
/**
|
|
* @file types.h
|
|
* @brief Width-named floating point aliases, to match the `<stdint.h>` spelling.
|
|
*
|
|
* C names its integers by width and its floats by rank, so a struct full of
|
|
* `uint32_t` and `float` reads inconsistently. These are the float spellings the
|
|
* rest of the library uses. They are plain aliases -- no guarantee beyond what
|
|
* the platform's `float` and `double` already provide -- and are deliberately
|
|
* *not* C23's `_Float32`/`_Float64`, which carry IEEE-754 requirements this
|
|
* library does not need.
|
|
*/
|
|
|
|
#ifndef _AKGL_TYPES_H_
|
|
#define _AKGL_TYPES_H_
|
|
|
|
#include <stdint.h>
|
|
|
|
/** @brief Single-precision float. Positions, velocities, and scale factors. */
|
|
typedef float float32_t;
|
|
/** @brief Double-precision float. Declared for symmetry; unused so far. */
|
|
typedef double float64_t;
|
|
|
|
#endif // _AKGL_TYPES_H_
|