DocBox-API-Referenz

DocBox-API-Referenz

bxSites docbox macht aus deinen BoxLang-/CFML-Klassen eine durchsuchbare, im Theme gestaltete API-Referenz innerhalb der eigenen Website - das BoxLang-Gegenstück zu den Javadoc-Generatoren, die das Gradle- und das Maven-Plugin Java-Projekten bieten.

BoxLang wird dabei nicht selbst geparst. DocBox erledigt das bereits gut, also läuft hier DocBox' eigene JSON-Strategie, deren Ergebnis in ganz normale Markdown-Seiten übersetzt wird. Sie landen im Content-Verzeichnis wie jede andere Seite, der nächste build gestaltet sie im Theme, nimmt sie in den Suchindex auf und liefert sie wie handgeschriebene Inhalte aus.

Voraussetzung

Das Modul bx-docbox muss in der BoxLang-Laufzeit installiert sein:

# OS-Binary
install-bx-module bx-docbox

# CommandBox
box install bx-docbox

Fehlt es, bricht der Verb mit einer verständlichen Meldung ab statt mit einem Stacktrace.

Schnellstart

bxSites docbox
bxSites build

Ganz ohne Konfiguration dokumentiert docbox diejenigen der üblichen BoxLang-Quellordner, die dein Projekt tatsächlich hat - models, handlers, bifs, components, interceptors - und schreibt die Seiten nach docs/api/docbox/.

Konfiguration

Alles ist optional; das vollständige Schema steht unter docbox.

docbox:
  projectTitle: "Meine API"
  mappings:
    models: models
    bifs: bifs
  excludes: "tests|build"
  pagePathPrefix: api/docbox
  tags: [ api, docbox ]

{
	"docbox": {
		"projectTitle": "Meine API",
		"mappings": { "models": "models", "bifs": "bifs" },
		"excludes": "tests|build",
		"pagePathPrefix": "api/docbox",
		"tags": [ "api", "docbox" ]
	}
}

[docbox]
projectTitle = "Meine API"
excludes = "tests|build"
pagePathPrefix = "api/docbox"
tags = [ "api", "docbox" ]

[docbox.mappings]
models = "models"
bifs = "bifs"

Zu jedem Schlüssel gibt es ein Flag, das ihn für einen Lauf überschreibt:

bxSites docbox --mappings:models=models --projectTitle="Meine API" \
	--pagePathPrefix=api/classes --tags=api,classes --excludes=tests

--jsonDir=<pfad> behält DocBox' eigene JSON-Ausgabe, statt sie zu verwerfen.

Was erzeugt wird

Drei Arten von Seiten: ein Überblicksindex, ein Index je Package und eine Seite je Klasse.

docs/api/docbox/
├── index.md                    # alle Packages und Klassen
├── models/
│   ├── index.md                # Klassen dieses Packages
│   ├── UserService.md
│   └── security/
│       ├── index.md
│       └── Auth.md

Eine Klassenseite zeigt den Docblock der Klasse, ihre deklarierten property-Blöcke und ihre Funktionen nach Sichtbarkeit gruppiert - Konstruktor zuerst, dann public, package und private - jeweils mit vollständiger Signatur, Hinweistext, Parametertabelle und @return-Text. Die Mitglieder stecken in derselben Alpine.js-Filterleiste wie die Javadoc-Seiten, damit auch eine lange Klasse überschaubar bleibt.

In die Navigation einbinden

Die erzeugten Seiten sind normaler Inhalt und erscheinen von selbst in der automatischen Verzeichnisnavigation. Für eine bewusste Platzierung nimm den Index in deine eigene nav auf:

nav:
  - title: Referenz
    children:
      - api/docbox/index.md

{
	"nav": [
		{ "title": "Referenz", "children": [ "api/docbox/index.md" ] }
	]
}

[[nav]]
title = "Referenz"
children = [ "api/docbox/index.md" ]

Was bewusst fehlt

• Keine Querverweise zwischen Klassen. Ein extends/implements-Ziel oder ein in einer Signatur genannter Typ erscheint als Inline-Code, auch wenn diese Klasse eine eigene Seite hat.
• Keine geerbten Mitglieder. Nur was eine Klasse selbst deklariert - genau wie in DocBox' eigener JSON-Ausgabe.
• Keine Navigationsverdrahtung. Die Seiten landen unter pagePathPrefix; die Platzierung bleibt dir überlassen.

Woher die Metadaten kommen

DocBox' JSON-Strategie serialisiert Name, Package, Typ, extends und Funktionen einer Klasse - aber nicht ihre deklarierten property-Blöcke, die implementierten Interfaces, ihre Annotationen auf Klassenebene oder den @return-Text einer Funktion. Diese vier sind für eine BoxLang-Referenz wichtig, Properties vor allem, weil sie jedes accessors-Feld und jede WireBox-inject-Angabe tragen. bx-sites liest sie deshalb aus denselben Klassenmetadaten nach, die DocBox selbst verwendet hat, und führt sie vor dem Rendern wieder zusammen. Nichts wird doppelt geparst.

Aus Gradle oder Maven

Beide Build-Plugins bieten diesen Generator ebenfalls an, für ein JVM-Projekt mit BoxLang-/CFML-Quellen - siehe Gradle-Plugin und Maven-Plugin.

Eine ColdBox-Anwendung zu dokumentieren ist ein eigener Verb - siehe ColdBox-Anwendungen.