BoxLang 🚀 A New JVM Dynamic Language Learn More...

DocBox

v4.2.1+3 Projects

All Contributors | Latest release

██████╗  ██████╗  ██████╗██████╗  ██████╗ ██╗  ██╗
██╔══██╗██╔═══██╗██╔════╝██╔══██╗██╔═══██╗╚██╗██╔╝
██║  ██║██║   ██║██║     ██████╔╝██║   ██║ ╚███╔╝
██║  ██║██║   ██║██║     ██╔══██╗██║   ██║ ██╔██╗
██████╔╝╚██████╔╝╚██████╗██████╔╝╚██████╔╝██╔╝ ██╗
╚═════╝  ╚═════╝  ╚═════╝╚═════╝  ╚═════╝ ╚═╝  ╚═╝

Welcome to DocBox!

DocBox is a JavaDoc-style documentation generator for your CFML codebase based on Mark Mandel's ColdDoc project.

Docs | Github | Ortus Community

Coldbox 5 Router class documentation, generated via DocBox

FEATURES

  • Read JavaDoc comment blocks
  • Document your class API - components, methods, and properties
  • Generate HTML documentation
  • Generate machine-readable JSON
  • generate XMI file which can be converted to a UML diagram

SYSTEM REQUIREMENTS

  • Lucee 5+
  • ColdFusion 2016+

Usage

Use the DocBox library to generate API docs from your CFC files. Install Docbox with CommandBox like so:

box install docbox

Standalone Application

If you want to use DocBox for document generation in your CFML application, then just drop it into any location and create a /docbox mapping to it. You will then instantiate the DocBox generator class with a strategy and properties for the strategy.

// use custom strategy found at class.path
docbox = new docbox.DocBox( strategy="class.path", properties={} );

// create with HTML strategy
docbox = new docbox.DocBox(
  strategy = "HTML",
  properties = {
    projectTitle="My Docs",
    outputDir="#expandPath( '/docs' )#"
  }
);

Generating Docs

To generate the documentation you will then execute the generate() method on the DocBox object and pass in the following parameters:

Generate Params

  • source : A path to the source location or an array of structs of locations that must have a dir and mapping key on it.
  • mapping : The base mapping for the folder source. Used only if source is a path
  • excludes : A regular expression that will be evaluated against all CFCs sent for documentation. If the regex matches the CFC name and path then the CFC will be excluded from documentation.
docbox.generate( source="/my/path", mapping="coldbox" );

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

Once the generation finalizes, you will see your beautiful docs!

Available Strategies & Properties

  • HTML - default
    • projectTitle : The HTML title
    • outputDir : The output directory
  • JSON
    • projectTitle : The HTML title
    • outputDir : The output directory
  • XMI
    • outputFile : The output file

CommandBox Command

There is a related project you can install which wraps up the DocBox library in a Custom CLI command so you can generate API docs from the command line.

box install commandbox-docbox

Read more here: https://github.com/Ortus-Solutions/commandbox-docbox


LICENSE

Apache License, Version 2.0.

BUGS + NEW FEATURES

Please use our Jira instance to create bugs and new feature issues: https://ortussolutions.atlassian.net/projects/DOCBOX

CREDITS & CONTRIBUTIONS

Thanks to Mark Mandel for allowing us to fork his project.

I THANK GOD FOR HIS WISDOM FOR THIS PROJECT

THE DAILY BREAD

"I am the way, and the truth, and the life; no one comes to the Father, but by me (JESUS)" Jn 14:1-12

Have Questions?

Come find us on the CFML Slack (#box-products channel) and ask us there. We'd be happy to help!

Ortus Community

Join us in our Ortus Community and become a valuable member of this project https://community.ortussolutions.com/c/communities/docbox/17. We are looking forward to hearing from you!

CHANGELOG

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog, and this project adheres to Semantic Versioning.


Unreleased

4.2.1 - 2024-02-13

4.1.1 - 2024-02-13

Fixed

  • Using old http instead of https on download URL

4.1.1 - 2024-02-13

Fixed

  • Missed branch identifier in build process

4.1.0 - 2024-02-13

Added

  • Adobe 2023 Testing and Support
  • New Github Actions
  • New supporting files
  • New build/Docs.cfc task for building the documentation using itself, before we where getting away with it because there was a previous DocBox version. Now we need to build the docs with the current version of DocBox.

Fixed

  • Build Versions and changelog
  • Removal of box.zip in root from old scripts

[4.0.0] - 2023-08-03

BREAKING

  • Dropped support for Adobe 2016. Adobe doesn't support ACF 16 anymore, so neither do we.

NEW

  • Added support for Adobe 2021
  • Added support for @myCustomTag custom docblock tags on methods. (Already supported on components and properties, but missing on methods).
  • Added GitHub Actions CI for automated testing, format checking, releases and more

FIX

  • Fixes support for Adobe 2018. (Mainly in the CommandBox strategy.)

[3.0.0]

Added

  • New json output strategy for machine-readable documentation
  • New addStrategy() method for multiple strategy support

Changed

  • Can configure strategy with "alias" name, like strategy="HTML".

Removed

  • Removed HTML as the default strategy. You will need to explicitly pass this to the constructor or to docbox.addStrategy( "HTML", props ) to set your desired output format.

Fixed

  • Fixed failing XMI strategy

[2.2.1]

Fixed

  • Bug on DocBox tracing errors, left over a couple of ()

[2.2.0]

Added

  • Better output of trace commands for CLI integration
  • Added @throws annotation to function definitions
  • Added @deprecated annotation to function definitions

[2.1.0]

Fixed

  • Varscoping issue to help with COMMANDBOX-399
  • BUGFIX: Missing pound sign in ExpandPath(), added better wording for custom strategy path
  • Fix cleanPath without a leading slash with regex updates

[2.0.7]

Fixed

  • Build process messed up folder structure. Basically 2.0.6 was unusable

[2.0.6]

Fixed

  • DOCBOX-1 - Extra slash breaks some links on S3-hosted docs

Improved

  • Updated build process

Added

  • Travis integration

[2.0.5]

Improved

  • Moved CommandBox command to its own repo

[2.0.4]

Improved

  • Update package directory and location for CommandBox command

[2.0.3]

Fixed

  • FireFox location bug

[2.0.2]

Fixed

  • Fixes on conversion to script

Improved

  • Updates on box.json for standalone installations

[2.0.1]

Fixed

  • Fixes for ACF

[2.0.0]

Improved

  • Updated to DocBox styles

$ box install docbox

No collaborators yet.
     
5.00 / 2
  • {{ getFullDate("2015-06-04T09:06:20Z") }}
  • {{ getFullDate("2024-02-13T21:02:28Z") }}
  • 12,890
  • 92,066