// Moved from docs/src/doxygen/DOXYGEN_QUICK_REFERENCE.adoc to docs/working/scratch/src/doxygen/DOXYGEN_QUICK_REFERENCE.adoc on 2026-06-16 (docs reorg Phase 2)
== Doxygen Quick Reference Card
:toc: left
:toc-title: Contents
:toclevels: 3

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


One-page cheat sheet for adding Doxygen documentation to StarForth code.

=== Essential Commands

[source,bash]
----
make docs          # Generate all formats (HTML, PDF, AsciiDoc, MD, Man)
make docs-html     # HTML only (fastest)
make docs-open     # Generate and open in browser
make docs-clean    # Remove generated docs
----

=== Basic Comment Syntax

==== File Header

[source,c]
----
/**
 * @file filename.h
 * @brief One-line file description
 * @author Your Name
 * @date 2025-10-01
 */
----

==== Function

[source,c]
----
/**
 * @brief One-line description
 * @param name Parameter description
 * @return Return value description
 */
type function(type name);
----

==== Struct

[source,c]
----
/**
 * @struct StructName
 * @brief One-line description
 */
typedef struct {
    int member;  /**< Member description */
} StructName;
----

==== Enum

[source,c]
----
/**
 * @enum EnumName
 * @brief One-line description
 */
typedef enum {
    VALUE_A,  /**< Description of A */
    VALUE_B   /**< Description of B */
} EnumName;
----

==== Macro

[source,c]
----
/**
 * @def MACRO_NAME
 * @brief One-line description
 */
#define MACRO_NAME value
----

==== Typedef

[source,c]
----
/**
 * @typedef TypeName
 * @brief One-line description
 */
typedef type TypeName;
----

=== Common Tags

[width="100%",cols="23%,29%,48%",options="header",]
|===
|Tag |Purpose |Example
|`+@brief+` |Short description |`+@brief Initialize VM+`

|`+@details+` |Detailed description
|`+@details Allocates memory and...+`

|`+@param name+` |Parameter |`+@param vm VM instance pointer+`

|`+@return+` |Return value |`+@return 0 on success+`

|`+@retval value+` |Specific return |`+@retval 0 Success+`

|`+@see+` |Cross-reference |`+@see vm_cleanup()+`

|`+@note+` |Important note |`+@note Thread-safe+`

|`+@warning+` |Warning |`+@warning May block+`

|`+@bug+` |Known bug |`+@bug Issue #42+`

|`+@todo+` |Future work |`+@todo Add optimization+`

|`+@deprecated+` |Deprecated |`+@deprecated Use foo() instead+`
|===

=== Conditions and Invariants

[source,c]
----
/**
 * @pre condition must be true before call
 * @post condition will be true after call
 * @invariant condition always true
 */
----

=== Code Examples

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

=== Grouping Functions

[source,c]
----
/**
 * @defgroup group_name Group Display Name
 * @brief Group description
 * @{
 */

/** Function in group */
void func1(void);

/** Another function in group */
void func2(void);

/** @} */ // End of group_name
----

=== Formatting

==== Lists

[source,c]
----
/**
 * List example:
 * - Item 1
 * - Item 2
 * - Item 3
 */
----

==== Numbered Lists

[source,c]
----
/**
 * Steps:
 * 1. First step
 * 2. Second step
 * 3. Third step
 */
----

==== Sections

[source,c]
----
/**
 * ## Section Title
 *
 * ### Subsection
 *
 * Content here.
 */
----

==== Emphasis

[source,c]
----
/**
 * *Italic text*
 * **Bold text**
 * `code text`
 */
----

=== Quick Templates

==== Simple Function

[source,c]
----
/**
 * @brief Short description
 * @param p1 First parameter
 * @param p2 Second parameter
 * @return Result
 */
int my_func(int p1, int p2);
----

==== Complex Function

[source,c]
----
/**
 * @brief Short description
 *
 * @details
 * Detailed explanation of what this function does,
 * how it works, and any important considerations.
 *
 * @param vm VM instance pointer
 * @param value Input value
 *
 * @return Result value
 * @retval 0 Success
 * @retval -1 Error
 *
 * @pre vm must be initialized
 * @post vm->state is updated
 *
 * @note Important implementation detail
 * @warning Potential issue to be aware of
 *
 * @see related_function()
 *
 * @par Example:
 * @code
 * int result = my_func(&vm, 42);
 * if (result < 0) {
 *     handle_error();
 * }
 * @endcode
 */
int my_func(VM *vm, int value);
----

==== Structure

[source,c]
----
/**
 * @struct MyStruct
 * @brief Short description
 *
 * @details
 * Detailed explanation of the structure's purpose
 * and usage.
 */
typedef struct MyStruct {
    /** @brief Field 1 description */
    int field1;

    /**
     * @brief Field 2 description
     * @note Special consideration for field2
     */
    char *field2;

    int field3;  /**< Field 3 inline description */
} MyStruct;
----

=== Best Practices

==== DO:

* ✅ Document ALL public functions
* ✅ Keep @brief to one line
* ✅ Use @details for longer explanations
* ✅ Provide examples for complex functions
* ✅ Cross-reference related functions with @see
* ✅ Document all parameters and return values
* ✅ Use @warning for dangerous operations
* ✅ Use @note for important details

==== DON’T:

* ❌ Document obvious things
* ❌ Repeat the function name in description
* ❌ Leave out parameter descriptions
* ❌ Forget to document return values
* ❌ Write vague descriptions
* ❌ Use unclear variable names in examples
* ❌ Forget to update docs when changing code

=== IDE Integration

==== Visual Studio Code

[arabic]
. Install "`Doxygen Documentation Generator`" extension
. Type `+/**+` above function
. Press Enter → template generated

==== CLion

[arabic]
. Built-in support
. Type `+/**+` and Enter
. Fill in generated template

==== Vim

[arabic]
. Install DoxygenToolkit.vim
. Position cursor on function
. Use `+:Dox+` command

=== Checking Your Work

[source,bash]
----
# Generate docs
make docs-html

# Check for warnings
cat docs/api/doxygen_warnings.log

# View in browser
make docs-open
----

=== Common Warnings and Fixes

[cols=",",options="header",]
|===
|Warning |Fix
|"`Member X is not documented`" |Add `+@param X description+`
|"`No documentation for function`" |Add `+@brief+` comment
|"`Return value not documented`" |Add `+@return description+`
|"`Warning: invalid cross-reference`" |Check @see target exists
|===

=== Example Workflow

[arabic]
. *Write function:*
+
[source,c]
----
void my_function(int param) {
    // implementation
}
----
. *Add basic docs:*
+
[source,c]
----
/**
 * @brief Does something with param
 * @param param Input value
 */
void my_function(int param) {
    // implementation
}
----
. *Generate and check:*
+
[source,bash]
----
make docs-html
cat docs/api/doxygen_warnings.log
----
. *View result:*
+
[source,bash]
----
make docs-open
----
. *Enhance docs if needed:*
+
[source,c]
----
/**
 * @brief Does something with param
 *
 * @details
 * More detailed explanation here.
 *
 * @param param Input value (must be > 0)
 * @return Processed result
 *
 * @pre param > 0
 * @post Result is always positive
 *
 * @see related_function()
 *
 * @par Example:
 * @code
 * int result = my_function(42);
 * @endcode
 */
void my_function(int param) {
    // implementation
}
----

=== Resources

* *Full Style Guide:* `+docs/DOXYGEN_STYLE_GUIDE.md+`
* *Example Header:* `+docs/examples/doxygen_example.h+`
* *User Guide:* `+docs/DOCUMENTATION_README.md+`
* *Documentation Overview:* `+docs/DOCUMENTATION_README.md+`
* *Doxygen Manual:* https://www.doxygen.nl/manual/

=== Time Estimates

* Simple function: 2-5 minutes
* Complex function with example: 10-15 minutes
* Struct with 10 fields: 10-15 minutes
* Complete header file (20 functions): 1-2 hours

'''''

*Keep this card handy while documenting!* *Print or bookmark for quick
reference.*