DocBox-Ausgabebeispiel

DocBox-Ausgabebeispiel

Ein echtes Beispiel dafür, was bxSites docbox erzeugt. Jede Seite unten stammt aus einem tatsächlichen Lauf gegen den gezeigten Quellcode - nichts davon ist von Hand geschrieben.

Gegeben diese Klasse im Ordner models/ eines Projekts:

/**
 * A single book on the shelf, immutable once created.
 *
 * @author Ortus Solutions
 */
class singleton accessors=true {

	/**
	 * The book's title
	 */
	property name="title" type="string";

	/**
	 * Where book records are read from
	 */
	property name="datasource" type="string" inject="coldbox:setting:bookDatasource";

	/**
	 * Build a book.
	 *
	 * @title The book's title
	 * @author The book's author
	 */
	function init( required string title, string author = "Unknown" ) {
		return this
	}

	/**
	 * Return a copy of this book with a new title.
	 *
	 * @newTitle The replacement title
	 *
	 * @return a copy carrying the new title
	 */
	Book function withTitle( required string newTitle ) {}

	private function normalize() {}
}

...schreibt bxSites docbox die Datei api/docbox/models/Book.md mit diesem Frontmatter:

---
title: "Book"
summary: "A single book on the shelf, immutable once created."
tags: [api, docbox]
---

Und diesen Body - unten nicht als Codeblock, sondern wirklich gerendert. Das ist der Body der erzeugten Seite, live, samt Filterleiste. Probier den Private-Chip oder tippe "title" in das Suchfeld:

Book

models.Book · Class

A single book on the shelf, immutable once created.

Annotations

• @accessors true
• @singleton

Properties

Worauf zu achten ist

• Dass es die Properties-Tabelle überhaupt gibt. DocBox' eigene JSON-Strategie lässt deklarierte property-Blöcke weg; bx-sites liest sie aus denselben Klassenmetadaten nach, die DocBox verwendet hat - deshalb stehen title und datasource hier mitsamt Hinweistext, und deshalb überlebt auch das WireBox-inject auf datasource.
• Der @return-Text überlebt aus demselben Grund - siehe die Returns-Zeile unter withTitle.
• Private Methoden sind enthalten, anders als beim Javadoc-Generator. DocBox meldet sie, also werden sie dokumentiert; der Private-Chip blendet sie aus, wenn man sie nicht sehen will.
• init ist der Konstruktor und bekommt einen eigenen Abschnitt vor den Methoden.

Siehe DocBox-API-Referenz für die Konfiguration und ColdBox-Ausgabebeispiel für das, was der ColdBox-Verb aus demselben Projekt macht.