// Moved from docs/src/build-and-tooling/DOCUMENTATION_README.adoc to docs/working/scratch/src/build-and-tooling/DOCUMENTATION_README.adoc on 2026-06-16 (docs reorg Phase 2)
== StarForth Documentation System
:toc: left
:toc-title: Contents
:toclevels: 3
xref:../README.adoc[← Back to Documentation Index]



Welcome to the StarForth documentation system! This document explains
how to generate, view, and contribute to the project documentation.

=== Quick Start

==== Generate All Documentation

[source,bash]
----
make docs
----

This generates:

* *AsciiDoc* - API documentation as AsciiDoc (docs/src/appendix/)
** Generated on-demand by `./scripts/generate-doxygen-appendix.sh`
** Periodically rebuilt by Jenkins
** Flat file structure, one file per source module

==== View Generated API Documentation

[source,bash]
----
# Generate the AsciiDoc API documentation
./scripts/generate-doxygen-appendix.sh

# View the index
cat docs/src/appendix/index.adoc
----

The AsciiDoc files are in `docs/src/appendix/` with one file per source module.

=== Installation Requirements

==== Required (Core Functionality)

[source,bash]
----
# Ubuntu/Debian
sudo apt-get install doxygen graphviz

# macOS
brew install doxygen graphviz

# Fedora/RHEL
sudo dnf install doxygen graphviz
----

==== Optional (Additional Formats)

===== For PDF Generation

[source,bash]
----
# Ubuntu/Debian
sudo apt-get install texlive-latex-base texlive-latex-extra

# macOS
brew install --cask mactex    # Full TeX Live (~4GB)
# Or for minimal install:
brew install --cask basictex  # Basic TeX (~100MB)

# Fedora/RHEL
sudo dnf install texlive-scheme-basic
----

===== For AsciiDoc and Markdown

[source,bash]
----
# All platforms
sudo apt-get install pandoc        # Debian/Ubuntu
brew install pandoc                # macOS
sudo dnf install pandoc            # Fedora/RHEL

# AsciiDoc HTML rendering (optional)
gem install asciidoctor
----

==== Verify Installation

[source,bash]
----
doxygen --version    # Should be >= 1.9.0
dot -V               # Graphviz, any recent version
pandoc --version     # Optional, for AsciiDoc/Markdown
pdflatex --version   # Optional, for PDF
----

=== Documentation Targets

[width="100%",cols="23%,40%,37%",options="header",]
|===
|Target |Description |Requirements
|`+make docs+` |Generate all formats |doxygen, graphviz (+ optional)

|`+make docs-html+` |HTML only (fast) |doxygen, graphviz

|`+make docs-pdf+` |PDF only |doxygen, graphviz, pdflatex

|`+make docs-open+` |Generate HTML and open in browser |doxygen,
graphviz

|`+make docs-clean+` |Remove generated docs |none
|===

=== Documentation Structure

....
docs/
├── src/                           # Source documentation (AsciiDoc)
│   ├── appendix/                  # Generated API documentation
│   │   ├── index.adoc             # API documentation index
│   │   ├── vm.c.adoc              # VM implementation documentation
│   │   ├── vm.h.adoc              # VM API header documentation
│   │   └── ...                    # One file per source module
│   │
│   ├── build-and-tooling/
│   │   ├── DOCUMENTATION_README.adoc  # This file
│   │   ├── DOXYGEN_STYLE_GUIDE.adoc   # Doxygen comment style guide
│   │   ├── ARCHITECTURE.adoc          # System architecture
│   │   └── ...
│   │
│   └── README.adoc                # Main documentation index
│
└── (other documentation sources)
....

=== Adding Documentation to Code

==== Step 1: Read the Style Guide

See DOXYGEN_STYLE_GUIDE.md for complete documentation standards.

==== Step 2: Use the Template

Use examples/doxygen_example.h as a template showing all documentation
styles.

==== Step 3: Document Your Code

Example for a function:

[source,c]
----
/**
 * @brief Push value onto data stack
 *
 * @details
 * Adds a value to the top of the data stack. Stack overflow
 * is checked and vm->error is set if stack is full.
 *
 * @param vm Pointer to VM instance
 * @param value Value to push
 *
 * @pre vm must be initialized
 * @pre vm->dsp < STACK_SIZE-1
 * @post vm->dsp incremented by 1
 * @post On error: vm->error is set
 *
 * @note This is a hot-path function - optimized for speed
 * @warning Always check vm->error after calling
 *
 * @see vm_pop()
 * @see vm_dup()
 *
 * @par Example:
 * @code
 * vm_push(&vm, 42);
 * if (vm.error) {
 *     fprintf(stderr, "Stack overflow\n");
 * }
 * @endcode
 */
void vm_push(VM *vm, cell_t value);
----

==== Step 4: Check Documentation

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

Fix any warnings about undocumented functions or parameters.

=== Documentation Coverage

==== Current Status

Run `+make docs+` and check the summary for documentation coverage:

* Target: 100% of public API headers
* Current: TBD (run `+make docs+` to check)

==== Priority Files to Document

[arabic]
. *High Priority* (User-facing API):
* `+include/vm.h+` - Core VM API
* `+include/word_registry.h+` - Word registration
* `+include/log.h+` - Logging API
* `+include/io.h+` - I/O operations
. *Medium Priority* (Developer API):
* `+src/word_source/include/*.h+` - Word implementations
* `+include/profiler.h+` - Performance profiling
* `+include/vm_debug.h+` - Debugging support
. *Low Priority* (Internal):
* Private implementation files (*.c)
* Test infrastructure headers

=== Integration with External Projects

==== Using StarForth Documentation in Your Project

If your project uses StarForth, you can link to our documentation:

[arabic]
. Generate our docs: `+make docs+`
. Reference our tag file: `+docs/src/appendix/starforth.tag+`
. Add to your Doxyfile:
+
....
TAGFILES = path/to/starforth/docs/src/appendix/starforth.tag=https://your-docs-url/
....

=== Continuous Integration

==== GitHub Actions Example

[source,yaml]
----
name: Documentation

on: [push, pull_request]

jobs:
  docs:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2

      - name: Install dependencies
        run: |
          sudo apt-get update
          sudo apt-get install -y doxygen graphviz

      - name: Generate documentation
        run: make docs-html

      - name: Check for warnings
        run: |
          if [ -s docs/src/appendix/doxygen_warnings.log ]; then
            echo "Documentation warnings found:"
            cat docs/src/appendix/doxygen_warnings.log
            exit 1
          fi

      - name: Deploy to GitHub Pages
        if: github.ref == 'refs/heads/master'
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./docs/src/appendix/html
----

=== Troubleshooting

==== Problem: "`doxygen: command not found`"

*Solution:* Install doxygen (see Installation Requirements above)

==== Problem: "`dot: command not found`"

*Solution:* Install graphviz package

==== Problem: "`pdflatex: command not found`"

*Solution:* PDF generation is optional. Either:

* Install TeX Live (see Installation Requirements)
* Or use `+make docs-html+` for HTML only

==== Problem: No graphs/diagrams in documentation

*Solution:* Install graphviz (`+sudo apt-get install graphviz+`)

==== Problem: Warnings about undocumented functions

*Solution:* Add Doxygen comments to those functions (see Style Guide)

==== Problem: "`No such file or directory`" when opening docs

*Solution:* Generate docs first: `+make docs-html+`

==== Problem: Pandoc errors for AsciiDoc/Markdown

*Solution:* AsciiDoc/Markdown generation is optional. Either:

* Install pandoc
* Or ignore (HTML/PDF are sufficient)

=== Man Pages

View generated man pages:

[source,bash]
----
# List all man pages
ls docs/src/appendix/man/

# View a specific page
man -l docs/src/appendix/man/vm_init.3

# Install to system (optional)
sudo cp docs/src/appendix/man/*.3 /usr/local/man/man3/
sudo mandb
man vm_init  # Now works without -l
----

=== Contributing Documentation

==== Documentation Pull Requests

When contributing code:

[arabic]
. *Document all public functions* - Use Doxygen comments
. *Include examples* - Show how to use complex functions
. *Check for warnings* - Run `+make docs-html+` and fix warnings
. *Update existing docs* - If changing behavior, update comments

==== Documentation-Only Changes

Documentation improvements are welcome! To contribute:

[arabic]
. Follow the DOXYGEN_STYLE_GUIDE.md
. Test with `+make docs+`
. Check for warnings in `+docs/src/appendix/doxygen_warnings.log+`
. Submit PR with clear description of changes

=== Advanced Configuration

==== Customizing Documentation

Edit `+Doxyfile+` to customize:

* Project name/version: `+PROJECT_NAME+`, `+PROJECT_NUMBER+`
* Input files: `+INPUT+`, `+FILE_PATTERNS+`
* Output formats: `+GENERATE_HTML+`, `+GENERATE_LATEX+`, etc.
* Diagram options: `+CALL_GRAPH+`, `+CALLER_GRAPH+`

==== Adding Custom Pages

Create Markdown files in `+docs/+` and add to `+Doxyfile+`:

....
INPUT = ... docs/MY_CUSTOM_PAGE.md
....

==== Theming HTML Output

Customize appearance:

....
HTML_EXTRA_STYLESHEET = docs/custom.css
HTML_COLORSTYLE = AUTO_LIGHT
....

=== Documentation Formats

==== HTML

* *Best for:* Interactive browsing, searching, navigation
* *Location:* docs/src/appendix/html/index.html
* *Features:* Hyperlinks, search, call graphs, file dependencies

==== PDF

* *Best for:* Printing, offline reading, comprehensive reference
* *Location:* docs/src/appendix/StarForth-API-Reference.pdf
* *Features:* Table of contents, index, bookmarks

==== AsciiDoc

* *Best for:* Technical writing, conversion to other formats
* *Location:* docs/src/appendix/asciidoc/starforth-api.adoc
* *Features:* Lightweight markup, easy to edit

==== Markdown

* *Best for:* GitHub viewing, copy-paste into wikis
* *Location:* docs/src/appendix/markdown/starforth-api.md
* *Features:* GFM (GitHub-Flavored Markdown)

==== Man Pages

* *Best for:* Unix command-line reference
* *Location:* docs/src/appendix/man/*.3
* *Features:* Traditional man page format, system integration

=== Questions?

* *Doxygen Manual:* https://www.doxygen.nl/manual/
* *Style Guide:* DOXYGEN_STYLE_GUIDE.md
* *Example Code:* examples/doxygen_example.h
* *Issues:* https://github.com/rajames440/StarForth/issues

'''''

*Generated by the StarForth Documentation System* *Sniff-tested by
Santino 🐕*
