header-api-review

name: header-api-review description: Cute Framework public header conventions and review checklist. Reference before creating or modifying any file in include/. user-invocable: false

CF Header Conventions

File Naming

Public headers: cute_<name>.h in include/
Source files: cute_<name>.cpp in src/

Generated vs Hand-Written Headers

Generated (do NOT edit manually): *_shd.h shader bytecode files produced by build/cute-shaderc
Hand-written (edit normally): all other include/cute_*.h files, including cute_shader_bytecode.h which defines shared shader structures and is NOT generated

Include Guards

Format: CF_<NAME>_H where <NAME> is the filename with cute_ prefix stripped, uppercased.

cute_graphics.h → CF_GRAPHICS_H
cute_sprite.h → CF_SPRITE_H
cute.h → CF_H

Copyright Header

Every file must begin with exactly:

/*
    Cute Framework
    Copyright (C) 2024 Randy Gaul https://randygaul.github.io/

    This software is dual-licensed with zlib or Unlicense, check LICENSE.txt for more info
*/

Header Structure

#ifndef CF_NAME_H
#define CF_NAME_H

#include "cute_defines.h"
// ... other includes with quotes for CF headers, angle brackets for system/SDL ...

//--------------------------------------------------------------------------------------------------
// C API

#ifdef __cplusplus
extern "C" {
#endif // __cplusplus

// ... C declarations ...

#ifdef __cplusplus
}
#endif // __cplusplus

//--------------------------------------------------------------------------------------------------
// C++ API

#ifdef __cplusplus
namespace Cute {
// ... C++ wrappers ...
} // namespace Cute
#endif // __cplusplus

#endif // CF_NAME_H

Naming Conventions

Public C functions: cf_ prefix, snake_case → cf_make_sprite, cf_draw_line
Public C structs/enums/typedefs: CF_ prefix → CF_Sprite, CF_PIXEL_FORMAT_R8
X-macro enum patterns: CF_<NAME>_DEFS macro + CF_<NAME> enum typedef
Static internal functions: s_ prefix — never in public headers
C++ namespace: namespace Cute, functions snake_case without cf_ prefix

Lifecycle Functions

Prefer cf_make_<name>(...) for creation and cf_destroy_<name>(...) for destruction. Avoid other lifecycle verbs unless strongly motivated.

Deprecation Pattern

Old name stays as the real implementation; new name is a CF_INLINE forwarder (or vice versa). The deprecated symbol's doc comment must include @deprecated Use cf_new_name instead.

/**
 * @function cf_old_function
 * @category example
 * @brief    Does the thing.
 * @deprecated Use cf_new_function instead.
 * @related  cf_new_function
 */
CF_INLINE void cf_old_function(int x) { cf_new_function(x); }

Documentation Format

All public declarations use /** ... */ block comments with * on every interior line. Never use /// style comments for documentation.

Tag ordering (follow this sequence)

@function / @struct / @enum — declaration kind; value is the symbol name
@category — groups symbol in docs (e.g. graphics, audio, input, allocator, sprite)
@brief — one-line summary
@param — one entry per parameter (omit if none)
@return — return value description (omit for void)
@remarks — extended notes, caveats, usage details (optional)
@example — code example with > title (optional)
@related — space-separated list of related symbols (highly recommended)

Function / typedef / macro

/**
 * @function cf_noise2
 * @category noise
 * @brief    Generates a random value given a 2D coordinate.
 * @param    noise  The noise settings.
 * @param    x      Noise at this x-component.
 * @param    y      Noise at this y-component.
 * @return   Returns a random value at the specified point.
 * @remarks  You're probably looking for image generation functions such as `cf_noise_pixels` or
 *           `cf_noise_fbm_pixels`. This function is fairly low-level.
 * @related  CF_Noise cf_make_noise cf_destroy_noise cf_noise2 cf_noise3 cf_noise4
 */
CF_API float CF_CALL cf_noise2(CF_Noise noise, float x, float y);

Struct — with `// @end` marker and `/* @member */` inline comments

/**
 * @struct   CF_Result
 * @category utility
 * @brief    Information about the result of a function, containing any potential error details.
 * @remarks  Check if a result is an error or not with `cf_is_error`.
 * @related  CF_Result cf_is_error cf_result_make cf_result_error cf_result_success
 */
typedef struct CF_Result
{
    /* @member Either 0 for success, or -1 for failure. */
    int code;

    /* @member String containing details about any error encountered. */
    const char* details;
} CF_Result;
// @end

Enum — X-macro pattern with `/* @entry /` and `/ @end */`

/**
 * @enum     CF_PlayDirection
 * @category sprite
 * @brief    The direction a sprite plays frames.
 * @related  CF_PlayDirection cf_play_direction_to_string CF_Animation
 */
#define CF_PLAY_DIRECTION_DEFS \
    /* @entry Flips through the frames of an animation forwards. */ \
    CF_ENUM(PLAY_DIRECTION_FORWARDS, 0) \
    /* @entry Flips through the frames of an animation backwards. */ \
    CF_ENUM(PLAY_DIRECTION_BACKWARDS, 1) \
    /* @end */

typedef enum CF_PlayDirection
{
    #define CF_ENUM(K, V) CF_##K = V,
    CF_PLAY_DIRECTION_DEFS
    #undef CF_ENUM
} CF_PlayDirection;

@example — indented code, title after `>`

 * @example > Creating a dynamic array and freeing it afterwards.
 *           dyna int* a = NULL;
 *           apush(a, 5);
 *           afree(a);

Code lines are indented to align under the title text (no triple-backtick fences in @example).

@remarks — embedded code uses fenced blocks

When @remarks contains a multi-line code snippet, use fenced ```c blocks:

 * @remarks  The members are stored tightly as an array. To access them:
 *
 *           ```c
 *           for (int i = 0; i < info.num_uniforms; ++i) {
 *               printf("%s\n", info.uniforms[i].block_name);
 *           }
 *           ```

Formatting rules

@param alignment: pad the parameter name so all descriptions align in a column
@remarks continuation: indent continuation lines to align with the first word of the description
@related: single space-separated line; include both the type (CF_Foo) and related functions
Inline code: backticks around all symbol names in prose: `cf_make_noise`, `CF_Noise`
Links: standard Markdown [text](url) for external docs
"Default X" / "Out parameter": suffix in @param descriptions where applicable

Includes

CF headers: quotes → #include "cute_defines.h"
System/SDL headers: angle brackets → #include <SDL3/SDL.h>
cute_defines.h is almost always needed (provides CF_INLINE, CF_API, CF_GLOBAL, etc.)

New Header Checklist

Copyright header (exact format)
Include guard CF_<NAME>_H
#include "cute_defines.h" at minimum
extern "C" { ... } wrapping for C section
All public C functions: cf_ prefix
All public types: CF_ prefix
/** ... */ Doxygen comments on all public declarations with @function/@struct/@enum, @category, @brief, and @related tags
namespace Cute C++ wrappers section
Added to include/cute.h umbrella include (follow that file's existing include ordering conventions)
Source file cute_<name>.cpp added to top-level CMakeLists.txt (in the CF_SRCS list)