| 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_Hcute_sprite.h → CF_SPRITE_Hcute.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"
#ifdef __cplusplus
extern "C" {
#endif
#ifdef __cplusplus
}
#endif
#ifdef __cplusplus
namespace Cute {
}
#endif
#endif
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.
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
CF_API float CF_CALL cf_noise2(CF_Noise noise, float x, float y);
Struct — with // @end marker and /* @member */ inline comments
typedef struct CF_Result
{
int code;
const char* details;
} CF_Result;
Enum — X-macro pattern with /* @entry */ and /* @end */
#define CF_PLAY_DIRECTION_DEFS \
\
CF_ENUM(PLAY_DIRECTION_FORWARDS, 0) \
\
CF_ENUM(PLAY_DIRECTION_BACKWARDS, 1) \
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
