// Moved from docs/src/doxygen/DOXYGEN_STYLE_GUIDE.adoc to docs/working/scratch/src/doxygen/DOXYGEN_STYLE_GUIDE.adoc on 2026-06-16 (docs reorg Phase 2)
== StarForth Doxygen Documentation Style Guide
:toc: left
:toc-title: Contents
:toclevels: 3

xref:../README.adoc[← Back to Documentation Index]


This guide explains how to add Doxygen (Javadoc-style) documentation to
StarForth source files.

=== Overview

StarForth uses Doxygen to automatically generate API documentation from
specially-formatted comments in source code. The documentation is
generated in multiple formats:

* *HTML* - Interactive web-based documentation
* *PDF* - Comprehensive reference manual
* *AsciiDoc* - Lightweight markup for technical docs
* *Markdown* - GitHub-friendly format
* *Man Pages* - Traditional Unix man pages

=== Quick Start

Generate documentation:

[source,bash]
----
make docs          # All formats
make docs-html     # HTML only (fast)
make docs-open     # Generate and open in browser
----

=== Documentation Comment Syntax

==== File Documentation

Every header (.h) and source (.c) file should start with a `+@file+`
block:

[source,c]
----
/**
 * @file vm.h
 * @brief StarForth Virtual Machine Core API
 *
 * @details
 * Detailed description of what this file contains and its purpose.
 * Can span multiple paragraphs and include code examples.
 *
 * @author R. A. James (rajames)
 * @date 2025-08-15
 * @version 1.0.0
 * @copyright CC0-1.0 (Public Domain)
 */
----

==== Function Documentation

Document functions with `+@brief+`, `+@param+`, `+@return+`, and
optional `+@details+`:

[source,c]
----
/**
 * @brief Initialize the StarForth virtual machine
 *
 * @details
 * Allocates VM memory, initializes stacks, sets up the dictionary,
 * and registers the FORTH-79 standard word set. After calling this
 * function, the VM is ready to interpret Forth code.
 *
 * Memory layout after initialization:
 * - Data stack: Empty (DSP = -1)
 * - Return stack: Empty (RSP = -1)
 * - Dictionary: Contains FORTH-79 core words
 * - HERE: Points to first free cell
 *
 * @param vm Pointer to uninitialized VM structure
 *
 * @pre vm must point to valid memory
 * @post vm->memory is allocated (VM_MEMORY_SIZE bytes)
 * @post vm->error is 0 on success, 1 on failure
 *
 * @note If initialization fails, vm->error will be set and
 *       vm->memory will be NULL. Always check vm->error after calling.
 *
 * @warning Do not use the VM if vm->error is non-zero after init
 *
 * @see vm_cleanup()
 * @see vm_interpret()
 *
 * @par Example:
 * @code
 * VM vm;
 * vm_init(&vm);
 * if (vm.error) {
 *     fprintf(stderr, "VM initialization failed\n");
 *     return 1;
 * }
 * vm_interpret(&vm, "42 . CR");
 * vm_cleanup(&vm);
 * @endcode
 */
void vm_init(VM *vm);
----

==== Structure/Typedef Documentation

Document types with `+@brief+`, `+@details+`, and member documentation:

[source,c]
----
/**
 * @typedef cell_t
 * @brief Forth cell type (signed 64-bit integer)
 *
 * The fundamental data unit in Forth. All stack operations work with cells.
 *
 * @note Size is platform-dependent: sizeof(signed long)
 * @warning Typically 64-bit but may be 32-bit on some platforms
 */
typedef signed long cell_t;

/**
 * @struct VM
 * @brief StarForth Virtual Machine state structure
 *
 * @details
 * Contains all VM state including stacks, memory, dictionary, and
 * compilation/interpretation state. One VM instance per Forth system.
 *
 * ## Memory Management
 * - VM owns vm.memory (allocated in vm_init)
 * - Dictionary entries are malloc'd separately
 * - User must call vm_cleanup() to free resources
 *
 * ## Thread Safety
 * VM is **not thread-safe**. Use one VM per thread or external locking.
 */
typedef struct VM {
    /** @brief Data stack (1024 cells) */
    cell_t data_stack[STACK_SIZE];

    /** @brief Return stack (1024 cells) */
    cell_t return_stack[STACK_SIZE];

    /**
     * @brief Data stack pointer (index of top element)
     *
     * @details
     * - Valid range: -1 (empty) to STACK_SIZE-1 (full)
     * - dsp == -1 means stack is empty
     * - dsp == STACK_SIZE-1 means stack is full
     */
    int dsp;

    /**
     * @brief Return stack pointer
     * @see dsp
     */
    int rsp;

    /**
     * @brief VM memory buffer (VM_MEMORY_SIZE bytes)
     * @note Allocated by vm_init(), freed by vm_cleanup()
     */
    uint8_t *memory;

    /** @brief Next free memory location (byte offset) */
    size_t here;

    /**
     * @brief Most recently defined word
     * @details Forms a linked list via DictEntry->link
     */
    DictEntry *latest;

    /** @brief Error flag (0=ok, 1=error) */
    int error;

    /** @brief Halted flag (0=running, 1=halted) */
    int halted;
} VM;
----

==== Enum Documentation

[source,c]
----
/**
 * @enum vm_mode_t
 * @brief VM compilation mode
 *
 * The VM operates in one of two modes:
 * - INTERPRET: Execute words immediately
 * - COMPILE: Add words to current definition
 */
typedef enum {
    MODE_INTERPRET = 0,  /**< Interpret mode (execute words) */
    MODE_COMPILE = 1     /**< Compile mode (build definitions) */
} vm_mode_t;
----

==== Macro/Define Documentation

[source,c]
----
/**
 * @def STACK_SIZE
 * @brief Maximum stack depth (1024 cells)
 *
 * Applies to both data stack and return stack. Stack overflow
 * detection is performed by vm_push() and vm_rpush().
 */
#define STACK_SIZE 1024

/**
 * @def VM_MEMORY_SIZE
 * @brief Total VM memory (5 MB)
 *
 * Layout:
 * - First 2 MB: Dictionary space
 * - Remaining 3 MB: User blocks (3072 blocks of 1KB each)
 */
#define VM_MEMORY_SIZE (5 * 1024 * 1024)
----

=== Special Documentation Tags

==== Grouping Related Functions

Use `+@defgroup+` and `+@ingroup+` to organize related functions:

[source,c]
----
/**
 * @defgroup stack_ops Stack Operations
 * @brief Data stack manipulation words
 * @{
 */

/** @brief Push value onto data stack */
void vm_push(VM *vm, cell_t value);

/** @brief Pop value from data stack */
cell_t vm_pop(VM *vm);

/** @} */ // End of stack_ops group
----

==== Cross-References

Use `+@see+` to link related functions:

[source,c]
----
/**
 * @brief Duplicate top stack element
 * @see vm_drop()
 * @see vm_swap()
 */
void vm_dup(VM *vm);
----

==== Code Examples

Use `+@code+` and `+@endcode+` for examples:

[source,c]
----
/**
 * @par Example:
 * @code
 * VM vm;
 * vm_init(&vm);
 * vm_push(&vm, 42);
 * vm_push(&vm, 10);
 * cell_t result = vm_pop(&vm);  // result = 10
 * @endcode
 */
----

==== Conditions and Warnings

[source,c]
----
/**
 * @pre Stack must have at least 2 elements
 * @post Stack depth reduced by 1
 *
 * @note This is an optimized hot-path function
 * @warning Caller must check stack depth first
 *
 * @bug Known issue #42: Overflow not detected in debug builds
 * @todo Add SIMD optimization for x86_64
 * @deprecated Use vm_add_checked() instead
 */
----

=== Documentation Quality Guidelines

==== DO:

* ✅ Document ALL public API functions
* ✅ Include code examples for complex functions
* ✅ Explain pre-conditions and post-conditions
* ✅ Use `+@warning+` for dangerous operations
* ✅ Cross-reference related functions with `+@see+`
* ✅ Keep `+@brief+` to one line
* ✅ Put detailed explanations in `+@details+`

==== DON’T:

* ❌ Document private static functions (unless complex)
* ❌ Repeat information already in function name
* ❌ Write obvious documentation (`+@brief Get value+` for
`+getValue()+`)
* ❌ Use vague descriptions ("`Does stuff with the stack`")
* ❌ Forget to update docs when changing code

=== Complete Example: Documented Header File

See `+examples/doxygen_example.h+` for a complete example showing all
documentation styles.

=== Checking Documentation

After adding documentation, check for warnings:

[source,bash]
----
make docs-html
cat docs/api/doxygen_warnings.log
----

Common warnings to fix:

* Undocumented functions
* Missing `+@param+` for parameters
* Missing `+@return+` for non-void functions
* Invalid cross-references in `+@see+`

=== Documentation Coverage

Check documentation coverage with:

[source,bash]
----
make docs
# Look for "Documented: X/Y files" in output
----

Goal: 100% documentation coverage for:

* All public headers in `+include/+`
* All word source headers in `+src/word_source/include/+`
* Key implementation files in `+src/+`

=== Viewing Generated Documentation

[source,bash]
----
make docs-open      # Generate and open HTML docs
xdg-open docs/api/html/index.html  # Open existing HTML
man -l docs/api/man/vm_init.3      # View man page
evince docs/api/StarForth-API-Reference.pdf  # View PDF
----

=== Integration with IDEs

==== Visual Studio Code

Install "`Doxygen Documentation Generator`" extension to auto-generate
documentation templates.

==== CLion / IntelliJ

Built-in Doxygen support. Use `+/**+` and press Enter to generate
template.

==== Vim

Use DoxygenToolkit.vim plugin for documentation templates.

'''''

*Questions?* See the Doxygen manual: https://www.doxygen.nl/manual/

*Sniff-tested by Santino 🐕*