# CommandBox users
box update docbox

# BoxLang users
boxlang install docbox

# Verify installation
box package show version

/**
 * Strategy Interface for DocBox Documentation Generation
 * <br>
 * This interface defines the contract that all DocBox documentation strategies must implement.
 * Strategies are responsible for generating documentation output in various formats (HTML, JSON, XMI, etc.)
 * from the component metadata collected by DocBox.
 * <br>
 * <small><em>Copyright 2015 Ortus Solutions, Corp <a href="www.ortussolutions.com">www.ortussolutions.com</a></em></small>
 */
interface {

	/**
	 * Execute the documentation generation strategy
	 *
	 * This method receives the complete metadata query from DocBox and is responsible for:
	 * - Processing the component metadata
	 * - Generating the appropriate output format
	 * - Writing files to the configured output location
	 *
	 * @metadata Query object containing all component metadata with columns:
	 *            - package: The package name
	 *            - name: The component name
	 *            - metadata: The complete component metadata structure
	 *            - type: The component type (component, interface, etc.)
	 *            - extends: The extended component name (if any)
	 *            - implements: The implemented interfaces (if any)
	 *
	 * @return The strategy instance for method chaining
	 */
	IStrategy function run( required query metadata );

}

docbox = new DocBox();
docbox.addStrategy( "JSON",
  {
      projectTitle = "DocBox API",
      outputDir = expandPath( "/resources/tmp" )
  } );

docbox.generate(
    source  = "#expandPath( '/docbox' )",
    mapping = "coldbox",
    excludes = "tests"
);

box install bx-docbox

install-bx-module bx-docbox

# Basic usage
boxlang module:docbox --source=/path/to/code --mapping=myapp --output-dir=/docs

# With project title and excludes
boxlang module:docbox --source=/src --mapping=myapp \
                       --excludes="(tests|build)" \
                       --output-dir=/docs \
                       --project-title="My API"

# Multiple source mappings
boxlang module:docbox --mappings:v1=/src/v1/models \
                       --mappings:v2=/src/v2/models \
                       --output-dir=/docs

# Using frames theme
boxlang module:docbox --source=/src --mapping=app \
                       --output-dir=/docs \
                       --theme=frames

# Show help
boxlang module:docbox --help

# Show version
boxlang module:docbox --version

this.mappings[ "docbox" ] = expandPath( "./libraries/doctorBox" );

<cfscript>
new docbox.DocBox().generate(
    source = expandPath( "./src" ),
    mapping = "myapp",
    outputDir = expandPath( "./docs" )
)
</cfscript>

var docbox = new docbox.DocBox();
docbox.addStrategy( "UML", { outputFile : "./tmp/docs/app-diagram.uml" })

new docbox.DocBox()
    .addStrategy( "HTML", {
        projectTitle : "My API Documentation",
        outputDir    : expandPath( './docs' ),
        theme        : "default"  // or "frames"
    } )
    .generate(
        source   = expandPath( "/app" ),
        mapping  = "app",
        excludes = "(tests|build)"
    );

new docbox.DocBox()
    .addStrategy( "HTML", {
        projectTitle : "My Docs",
        outputDir    : expandPath( '/docs/html' ),
        theme        : "default"
    } )
    .addStrategy( "JSON", {
        projectTitle : "My Docs",
        outputDir    : expandPath( '/docs/json' )
    } )
    .addStrategy( "XMI", {
        outputFile : expandPath( '/docs/diagram.uml' )
    } )
    .generate(
        source   = expandPath( "/app" ),
        mapping  = "app",
        excludes = "(tests|build)"
    );

// Use the modern SPA theme (default)
docbox.addStrategy( "HTML", {
    projectTitle : "My API",
    outputDir    : expandPath( './docs' ),
    theme        : "default"
} );

// Use the traditional frames theme
docbox.addStrategy( "HTML", {
    projectTitle : "My API",
    outputDir    : expandPath( './docs' ),
    theme        : "frames"
} );

docbox.generate(
    source   = expandPath( '/myapp' ),
    mapping  = 'myapp',
    excludes = '(tests|build)'
);

docbox.generate(
    source = [
        { dir: expandPath( '/app/models' ), mapping: 'app.models' },
        { dir: expandPath( '/app/handlers' ), mapping: 'app.handlers' },
        { dir: expandPath( '/plugins' ), mapping: 'plugins' }
    ],
    excludes = '(tests|specs)'
);

# Basic usage
boxlang module:docbox --source=/path/to/code \
                       --mapping=myapp \
                       --output-dir=/docs

# With options
boxlang module:docbox --source=/app \
                       --mapping=myapp \
                       --output-dir=/docs \
                       --project-title="My API" \
                       --theme=frames \
                       --excludes="(tests|build)"

# Multiple sources
boxlang module:docbox --mappings:models=/app/models \
                       --mappings:handlers=/app/handlers \
                       --output-dir=/docs

variables.docbox = new docbox.DocBox(
    strategy   = "docbox.strategy.uml2tools.XMIStrategy",
    properties = {
        projectTitle : "DocBox Tests",
        outputFile   : variables.testOutputFile
    }
);

docBox = new DocBox();
docBox.addStrategy( "UML", { projectFile = expandPath( "./uml/docbox.uml" ) });
docbox.generate( expandPath("/docbox"), "docbox" );

{
    "$id": "point-to-public-json-schema.json",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Package documentation index",
    "description": "This class index links to each generated class documentation JSON file.",
    "required": [],
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        },
        "classes": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "path": {
                        "type": "string"
                    }
                }
            }
        },
        "packages": {
            "type": "object",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "path": {
                        "type": "string"
                    }
                }
            }
        }
    }
}

{
    "$id": "point-to-public-json-schema.json",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Package documentation index",
    "description": "Index file documenting each coldfusion component inside a package level - i.e. per directory.",
    "required": [],
    "type": "object",
    "properties": {
        "title": {
            "type": "string"
        },
        "classes": {
            "type": "array",
            "items": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string"
                    },
                    "path": {
                        "type": "string"
                    }
                }
            }
        }
    }
}

{
    "$id": "point-to-public-json-schema.json",
    "$schema": "http://json-schema.org/draft-07/schema#",
    "title": "Class documentation",
    "description": "Documents a single class in a ColdFusion package.",
    "required": [],
    "definitions": {
        "function" : {
            "type" : "object",
            "properties": {
                "name" : { "type" : "string" },
                "hint" : { "type" : "string" },
                "description" : { "type" : "string" },
                "access" : { "type" : "string" },
                "parameters" : {
                    "type" : "array",
                    "items": { "$ref" : "#/definitions/parameter" }
                },
                "returnType" : { "type" : "string" },
                "returnFormat" : { "type" : "string" },
                "position" : {
                    "type" : "object",
                    "properties" : {
                        "start" : { "type" : "integer" },
                        "end" : { "type" : "integer" }
                    }
                }
            }
        },
        "parameter" : {
            "type" : "object",
            "properties": {
                "type" : { "type" : "string" },
                "name" : { "type" : "string" },
                "required" : { "type" : "boolean" },
                "default" : { "type" : "string" }
            }
        }
    },
    "type": "object",
    "properties": {
        "name" : { "type": "string" },
        "package" : { "type": "string" },
        "type" : { "type": "string" },
        "extends" : { "type" : "string" },
        "implements" : { "type" : "string" },
        "hint" : { "type" : "string" },
        "description" : { "type" : "string" },
        "properties" : {
            "description" : "Literally the component properties set via `property` or `cfproperty`.",
            "type" : "object",
            "properties": {
                "type" : { "type" : "string" },
                "name" : { "type" : "string" },
                "access" : { "type" : "string" },
                "hint" : { "type" : "string" },
                "default" : { "type" : "string" },
                "required" : { "type" : "boolean" }
            }
        },
        "constructor" : { "$ref": "#/definitions/function" },
        "functions" : {
            "type" : "array",
            "items" : { "$ref": "#/definitions/function" }
        }
    }
  }

new docbox.DocBox()
    .addStrategy( "CommandBox", {
        projectTitle : "My CommandBox Commands",
        outputDir    : expandPath( "/docs/commands" )
    } )
    .generate(
        source  = expandPath( "/modules/my-commands/commands/" ),
        mapping = "my-commands"
    );

new docbox.DocBox()
    .addStrategy(
        new docbox.strategy.CommandBox.CommandBoxStrategy(
            outputDir    = expandPath( "/docs/commandbox" ),
            projectTitle = "CommandBox CLI Reference"
        )
    )
    .generate(
        source  = "/commandbox/cfml/system/modules_app/",
        mapping = "commandbox.commands"
    );

outputDir/
├── index.html                  - Main entry point (frameset)
├── overview-summary.html       - Namespace overview
├── overview-frame.html         - Navigation sidebar
├── css/                        - CSS stylesheets
├── js/                         - JavaScript files
├── bootstrap/                  - Bootstrap assets
└── {namespace}/
    ├── package-summary.html    - Namespace detail page
    └── {command}.html          - Individual command documentation

server start
server stop
package show
package set

new docbox.DocBox()
    .addStrategy( "CommandBox", {
        projectTitle : "CommandBox CLI Reference",
        outputDir    : expandPath( "/docs/commandbox-core" )
    } )
    .generate(
        source  = "/commandbox/cfml/system/modules_app/",
        mapping = "commandbox.commands",
        excludes = "(tests|build)"
    );

new docbox.DocBox()
    .addStrategy( "CommandBox", {
        projectTitle : "My CLI Module",
        outputDir    : expandPath( "/docs/my-module" )
    } )
    .generate(
        source  = expandPath( "/modules/my-module/commands/" ),
        mapping = "my-module.commands"
    );

var docbox = new docbox.DocBox()
    .addStrategy( "CommandBox", {
        projectTitle : "All Command Modules",
        outputDir    : expandPath( "/docs/all-commands" )
    } );

docbox.generate(
    source = [
        { dir: expandPath( "/modules/module1/commands/" ), mapping: "module1" },
        { dir: expandPath( "/modules/module2/commands/" ), mapping: "module2" }
    ]
);

docbox = new DocBox();

docbox = new DocBox();
docbox.addStrategy( "HTML", {
    projectTitle : "My Docs",
    outputDir    : expandPath( "/mydocs" ),
    theme        : "default"  // or "frames"
} );

docbox = new DocBox();
docbox.addStrategy( "HTML", {
    projectTitle : "My API Docs",
    outputDir    : expandPath( "/mydocs" ),
    theme        : "frames"
} );

docbox.generate(
    source  = "#expandPath( '/docbox' )",
    mapping = "coldbox",
    excludes = "tests"
);

box install bx-docbox

install-bx-module bx-docbox

boxlang module:docbox [options]

boxlang module:docbox --source=/src/models \
                       --mapping=models \
                       --output-dir=/docs

boxlang module:docbox --source=/src \
                       --mapping=myapp \
                       --excludes="(tests|build)" \
                       --output-dir=/docs \
                       --project-title="My API"

boxlang module:docbox --source=/src \
                       --mapping=app \
                       -o=/docs

boxlang module:docbox --mappings:v1=/src/v1/models \
                       --mappings:v2=/src/v2/models \
                       --output-dir=/docs \
                       --project-title="API Docs"

boxlang module:docbox --source=/src \
                       --mapping=app \
                       --output-dir=/docs \
                       --theme=frames

boxlang module:docbox --source="[{'dir':'/src/models', 'mapping':'models'}, {'dir':'/src/services', 'mapping':'services'}]" \
                       --output-dir=/docs \
                       --project-title="My API"

boxlang module:docbox --source=tests/resources/coldbox \
                       --mapping=coldbox \
                       --excludes="(tests|build)" \
                       --output-dir=tests/apidocs \
                       --project-title="ColdBox Framework" \
                       --theme=default

═══════════════════════════════════════════════════════════════════
  📚 DocBox Documentation Generator
═══════════════════════════════════════════════════════════════════

📂 Source:  /Users/myapp/src/models
🔗 Mapping: models
📁 Output:  /Users/myapp/docs

⏳ Starting generation, please wait...

🥊 Generation complete!
Documentation available at: /Users/myapp/docs

boxlang module:docbox --help

boxlang module:docbox --version

❌ ERROR: No valid source mappings found.

❌ ERROR: --output-dir is required

boxlang module:docbox --source=/src --mapping=app --output-dir=/docs

⚠️  Warning: '/path/to/source' does not exist.

boxlang module:docbox --source=/src --mapping=app \
                       --output-dir=/docs \
                       --theme=default

boxlang module:docbox --source=/src --mapping=app \
                       --output-dir=/docs \
                       --theme=frames

component {
    function run() {
        command( "boxlang" )
            .params(
                "module:docbox",
                "--source=#getCWD()#/models",
                "--mapping=models",
                "--output-dir=#getCWD()#/docs",
                "--project-title=My Project",
                "--theme=default"
            )
            .run();
    }
}

- name: Generate API Documentation
  run: |
    boxlang module:docbox \
      --source=./src \
      --mapping=myapp \
      --output-dir=./build/docs \
      --project-title="My Application" \
      --theme=default

# Correct usage
boxlang module:docbox --source=/src --mapping=app --output-dir=/docs

# Or with mappings
boxlang module:docbox --mappings:app=/src --output-dir=/docs

box update docbox

Class [myapp.MyClass] not found

// If your component is at: /src/models/User.cfc
// And its component declaration is: component { }
// And you access it via: new models.User()

new docbox.DocBox()
    .addStrategy( "HTML", { outputDir: "/docs" } )
    .generate(
        source  = expandPath( "/src" ),      // Source directory
        mapping = "models"                    // Base mapping
    );

// Correct - matches relative paths
excludes = "(tests|build|\.git)"

// Incorrect - won't match absolute paths
excludes = "/full/path/to/tests"

/**
 * User management service
 *
 * @author Your Name
 */
component {

    /**
     * Gets a user by ID
     *
     * @id The user ID
     * @return User object or null
     */
    public function getUser( required numeric id ) {
        // implementation
    }
}

/**
 * Gets all active users
 *
 * @return Array of User objects
 * @doc.type Array<User>
 */
public array function getUsers() {
    return [];
}

box update docbox

// Explicitly specify theme
new docbox.DocBox()
    .addStrategy( "HTML", {
        outputDir: "/docs",
        theme: "default"  // or "frames"
    } )
    .generate( source: "/src", mapping: "app" );

Command [module:docbox] not found

# For CommandBox web runtimes
box install bx-docbox

# For BoxLang OS runtime
install-bx-module bx-docbox

# Verify installation
boxlang module:docbox --version

box config set server.jvm.heapSize=1024

// Document modules separately
new docbox.DocBox()
    .addStrategy( "HTML", { outputDir: "/docs/module1" } )
    .generate( source: "/src/module1", mapping: "module1" );

new docbox.DocBox()
    .addStrategy( "HTML", { outputDir: "/docs/module2" } )
    .generate( source: "/src/module2", mapping: "module2" );

excludes = "(tests|specs|build|node_modules|\.git|vendor)"

# Reinstall the module
box uninstall bx-docbox
box install bx-docbox

# Or force module reload
box reload

box update docbox

new docbox.DocBox()
    .addStrategy( "JSON", {
        projectTitle: "My API",
        outputDir: expandPath( "/docs/json" )
    } )
    .generate(
        source: expandPath( "/src" ),  // Use expandPath()
        mapping: "app"
    );

new docbox.DocBox()
    .addStrategy( "XMI", {
        outputFile: expandPath( "/docs/diagram.uml" )  // Not outputDir!
    } )
    .generate( source: "/src", mapping: "app" );

try {
    var docbox = new docbox.DocBox()
        .addStrategy( "HTML", {
            outputDir: expandPath( "/docs" )
        } );

    writeDump( "Starting documentation generation..." );

    docbox.generate(
        source: expandPath( "/src" ),
        mapping: "app"
    );

    writeDump( "Generation complete!" );
} catch ( any e ) {
    writeDump( var=e, label="DocBox Error" );
    rethrow;
}

component = createObject( "component", "myapp.MyClass" );
metadata = getComponentMetadata( component );
writeDump( metadata );

testFile = expandPath( "/docs/test.txt" );
fileWrite( testFile, "test" );
fileDelete( testFile );
writeDump( "Output directory is writable" );

// No initial strategy
docbox = new docbox.DocBox();

// With strategy alias
docbox = new docbox.DocBox( strategy: "HTML", properties: {
    outputDir: "/docs",
    projectTitle: "My API"
} );

// With strategy instance
docbox = new docbox.DocBox(
    strategy: new docbox.strategy.api.HTMLAPIStrategy(
        outputDir: "/docs",
        projectTitle: "My API"
    )
);

DocBox function addStrategy(
    required any strategy,
    struct properties = {}
)

// Single strategy
docbox.addStrategy( "HTML", {
    outputDir: "/docs",
    projectTitle: "My Docs"
} );

// Multiple strategies
docbox
    .addStrategy( "HTML", { outputDir: "/docs/html" } )
    .addStrategy( "JSON", { outputDir: "/docs/json" } );

// Strategy instance
docbox.addStrategy(
    new docbox.strategy.api.HTMLAPIStrategy(
        outputDir: "/docs"
    )
);

DocBox function setStrategy(
    required any strategy,
    struct properties = {}
)

DocBox function generate(
    required any source,
    required string mapping,
    string excludes = "",
    boolean throwOnError = false
)

// Basic usage
docbox.generate(
    source: expandPath( "/src" ),
    mapping: "myapp"
);

// With exclusions
docbox.generate(
    source: expandPath( "/src" ),
    mapping: "myapp",
    excludes: "(tests|build|\.git)"
);

// Multiple sources
docbox.generate(
    source: [
        { dir: expandPath( "/src/models" ), mapping: "models" },
        { dir: expandPath( "/src/services" ), mapping: "services" }
    ]
);

array function getStrategies()

property name="outputDir" type="string";
property name="projectTitle" type="string" default="Untitled";

IStrategy function run( required query qMetaData )

query function getPackageQuery( required query qMetaData, required string package )

query function getFunctionQuery(
    required struct metadata,
    string access = ""
)

query function getPropertyQuery( required struct metadata )

struct function buildPackageTree( required array packageNames )

// Input: [ "coldbox.system.web", "coldbox.system.cache" ]
// Output: { coldbox: { system: { web: {}, cache: {} } } }

void function visitPackageTree(
    required struct tree,
    required any visitor,
    string prefix = ""
)

HTMLAPIStrategy function init(
    required string outputDir,
    string projectTitle = "Untitled",
    string theme = "default"
)

strategy = new docbox.strategy.api.HTMLAPIStrategy(
    outputDir: expandPath( "/docs" ),
    projectTitle: "My API",
    theme: "default"
);

property name="outputDir" type="string";
property name="projectTitle" type="string" default="Untitled";
property name="theme" type="string" default="default";

IStrategy function run( required query qMetaData )

JSONAPIStrategy function init(
    required string outputDir,
    string projectTitle = "Untitled"
)

property name="outputDir" type="string";
property name="projectTitle" type="string" default="Untitled";

XMIStrategy function init( required string outputFile )

strategy = new docbox.strategy.uml2tools.XMIStrategy(
    outputFile: expandPath( "/docs/diagram.uml" )
);

property name="outputFile" type="string";

CommandBoxStrategy function init(
    required string outputDir,
    string projectTitle = "Untitled"
)

strategy = new docbox.strategy.CommandBox.CommandBoxStrategy(
    outputDir: expandPath( "/docs/commands" ),
    projectTitle: "My CLI Commands"
);

IStrategy function run( required query metadata )

qMetaData = queryNew(
    "package,name,extends,metadata,type,implements,fullextends,currentMapping",
    "varchar,varchar,varchar,any,varchar,varchar,varchar,varchar"
);

component extends="docbox.strategy.AbstractTemplateStrategy" {

    property name="outputDir" type="string";

    function init( required string outputDir ) {
        variables.outputDir = arguments.outputDir;
        return this;
    }

    function run( required query qMetaData ) {
        // Your implementation here
        return this;
    }
}

new docbox.DocBox()
    .addStrategy( new path.to.MyCustomStrategy(
        outputDir: "/docs"
    ) )
    .generate( source: "/src", mapping: "app" );

new docbox.DocBox()
    .addStrategy( "HTML", { outputDir: "/docs/html" } )
    .addStrategy( "JSON", { outputDir: "/docs/json" } )
    .generate( source: "/src", mapping: "app" );

var docbox = new docbox.DocBox();

docbox.addStrategy( "HTML", {
    outputDir: "/docs/html",
    projectTitle: "My API",
    theme: "default"
} );

docbox.addStrategy( "JSON", {
    outputDir: "/docs/json",
    projectTitle: "My API"
} );

docbox.addStrategy( "XMI", {
    outputFile: "/docs/diagram.uml"
} );

docbox.generate(
    source: expandPath( "/src" ),
    mapping: "myapp",
    excludes: "(tests|build)"
);

try {
    new docbox.DocBox()
        .addStrategy( "HTML", { outputDir: "/docs" } )
        .generate(
            source: "/src",
            mapping: "app",
            throwOnError: true  // Throw on invalid components
        );
} catch ( any e ) {
    // Handle errors
    writeLog( e.message );
    rethrow;
}

/**
 * This is a Javadoc compliant comment for DocBox
 */

/**
 * get Java FileInputStream for resource bundle
 *
 * @rbFilePath path + filename for resource, including locale + .properties
 *
 * @return java.io.FileInputStream
 *
 * @throws ResourceBundle.InvalidBundlePath
 */
public function getResourceFileInputStream( required string rbFilePath ){
}

/**
 * get Java FileInputStream for resource bundle
 *
 * @rbFilePath path + filename for resource, including locale + .properties
 * @rbFilePath.deprecated true
 *
 * @return java.io.FileInputStream
 * @throws ResourceBundle.InvalidBundlePath
 */
public function getResourceFileInputStream( required string rbFilePath ){
}

/**
 * Get foo array
 *
 * @doc.type com.Foo
 */
private array function getFooArray(){
  return variables.foo;
}

// Inline
private array function getFooArray() doc.type="com.Foo"{
  return variables.foo;
}

/**
 * Set my struct
 *
 * @myStruct.doc.type uuid,string
 */
private void function setMyStruct( required struct myStruct ){
  instance.myStruct = arguments.myStruct;
}

// Inline
private void function setMyStruct(
  required struct myStruct doc.type="uuid,string"
){
  instance.myStruct = arguments.myStruct;
}

@doc.type TypeName
@doc.type KeyType,ValueType

/**
 * Gets all active users from the database
 *
 * @return Array of User objects
 * @doc.type Array<User>
 */
public array function getActiveUsers() {
    return queryExecute( "SELECT * FROM users WHERE active = 1" )
        .map( function( row ) {
            return new User( row );
        } );
}

/**
 * Gets user preferences as a configuration map
 *
 * @return Struct mapping setting names to values
 * @doc.type Struct<String,Any>
 */
public struct function getUserPreferences() {
    return {
        "theme": "dark",
        "fontSize": 14,
        "autoSave": true
    };
}

/**
 * Processes a batch of user records
 *
 * @users Array of User objects to process
 * @users.doc.type Array<User>
 */
public void function processBatch( required array users ) {
    for ( var user in arguments.users ) {
        user.process();
    }
}

/**
 * Updates user settings with validation
 *
 * @settings Map of setting names to their values
 * @settings.doc.type Struct<String,Any>
 */
public void function updateSettings( required struct settings ) {
    validateSettings( arguments.settings );
    saveSettings( arguments.settings );
}

// Return type with inline generic
public array function getUsers() doc.type="Array<User>" {
    return entityLoad( "User" );
}

// Parameter with inline generic
public void function setCache(
    required struct cache doc.type="String,Any"
) {
    variables.cache = arguments.cache;
}

/**
 * Gets a map of user IDs to their roles
 *
 * @return Map of numeric user IDs to arrays of role names
 * @doc.type Struct<Numeric,Array<String>>
 */
public struct function getUserRoles() {
    return {
        1: [ "admin", "editor" ],
        2: [ "viewer" ],
        3: [ "editor", "contributor" ]
    };
}

/**
 * Gets a complex data structure for reporting
 *
 * @return Nested structure containing report data
 * - Outer struct: Department name -> Department data
 * - Department data: Struct with "users" (Array<User>) and "metrics" (Struct<String,Numeric>)
 * @doc.type Struct<String,Struct>
 */