OpenParable
Skip to content
← Back to skills

Header API Review

Development
header-api-review

Header API Review is an Agent Skill for development published in the RandyGaul/cute_framework repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.

Cute Framework public header conventions and review checklist. Reference before creating or modifying any file in include/.

View on GitHub ↗
QUICK START

How to use this skill

Bring this guide into your coding agent with a prompt tailored to the tool you use.

  1. Open your project in Codex.
  2. Copy and paste the prompt below.
  3. Review files and risks before approving any action.
Prompt to paste
Inspect the Agent Skill at https://github.com/RandyGaul/cute_framework/blob/HEAD/.claude/skills/header-api-review/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/header-api-review, but wait for my approval before writing files or running scripts.

Copying this prompt does not install or run the skill. Review third-party files before use.

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)

  1. @function / @struct / @enum — declaration kind; value is the symbol name
  2. @category — groups symbol in docs (e.g. graphics, audio, input, allocator, sprite)
  3. @brief — one-line summary
  4. @param — one entry per parameter (omit if none)
  5. @return — return value description (omit for void)
  6. @remarks — extended notes, caveats, usage details (optional)
  7. @example — code example with > title (optional)
  8. @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)