Ejemplo de salida de DocBox

Ejemplo de salida de DocBox

Un ejemplo real de lo que produce bxSites docbox. Cada página de abajo salió de una ejecución real contra el código que se muestra: nada aquí es una ilustración escrita a mano.

Dada esta clase en la carpeta models/ de un proyecto:

/**
 * 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() {}
}

...bxSites docbox escribe api/docbox/models/Book.md con este frontmatter:

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

Y este cuerpo, reproducido abajo no como bloque de código sino renderizado de verdad: este es el cuerpo real de la página generada, en vivo, con su barra de filtro. Prueba el chip Private, o escribe "title" en el buscador:

Book

models.Book · Class

A single book on the shelf, immutable once created.

Annotations

• @accessors true
• @singleton

Properties

En qué fijarse

• Que la tabla de propiedades exista siquiera. La estrategia JSON de DocBox descarta los bloques property declarados; bx-sites los relee de los mismos metadatos de clase que usó DocBox, y por eso title y datasource aparecen aquí con sus descripciones intactas, y por eso sobrevive el inject de WireBox en datasource.
• El texto de @return también sobrevive, por la misma razón: mira la línea Returns bajo withTitle.
• Los métodos privados se incluyen, a diferencia del generador de Javadoc. DocBox los reporta, así que se documentan, y el chip Private los oculta cuando no los quieres.
• init es el constructor, con su propia sección antes de los métodos.

Consulta Referencia de API con DocBox para la configuración y Ejemplo de salida de ColdBox para lo que el verbo ColdBox produce del mismo proyecto.