Added
Added an example object
const api = require('quantum-api')
const html = require('quantum-html')
const htmlOptions = {
entityTransforms: {
api: api.entityTransforms()
}
}
module.exports = {
pipeline: [
html(htmlOptions)
],
pages: 'index.um'
}@api example-api
@function makeCoffee
@description
A function for making coffee
@arg sugar [Boolean]
@description
Whether to add Sugar
@arg milk [Boolean]
@description
Whether to add milk@arg may be an object so could contain @property entities. @api
@function functionName
@arg stringParma [String]
@arg objectParam [Object]
@property objectProp [Object]
@property anotherObjectProp [Object]
@description: And so on...
@object objectName [Object]
@property objectProp [Object]
@property anotherObjectProp [Object]
@description: And so on...@api entity @api apiName@api apiName
@group Header
@object obj1
@group [Multi word header]
@object obj2@changelog 1.0.0
@description
Description of changes in this version
@entry
@header javascript
@function jsFunction1
@change added
@description: Added jsFunction1
@group Changelog group
@entry
@header javascript
@function jsFunction2
@change added
@description: Added jsFunction2@changelogList
@changelog 1.0.0
@description
Description of changes in this version
@entry
@header javascript
@function jsFunction1
@change added
@description: Added jsFunction1
@group Changelog group
@entry
@header javascript
@function jsFunction2
@change added
@description: Added jsFunction2
@changelog 2.0.0
@description
Description of changes in this version
@entry
@header javascript
@function jsFunction1
@change updated
@description: Updated jsFunction1@api sections. @changelogList
@groupByApi true@inline file or set of files. @changelogList
@reverseVisibleList true@changelogList
@version 1.0.0
@link [path/to/version/1.0.0]
@description
Description of the changes in version 1@function collapsedFunction
@collapsed true
@description
Collapsed function
@function openFunction
@collapsed false
@description
Open function@function collapsedFunction
@collapsible true
@description
Collapsible function
@function openFunction
@collapsible false
@description
Open function@property propertyName
@description: Description of property@function functionName
@description
A function that returns true
@extra
@bold[Example]:
@@codeblock js
functionName() // returns true@api apiName
@function functionName
@group Stuff
@object object1javascript @description
@extra
@arg
@arg?@api
@object objectName
@collapsed false
@property prop1 [Boolean]
@collapsed false
@default: @code[false]
@function functionName
@collapsed false
@arg? param1 [Boolean]
@collapsed false
@default: @code[true]@description
@extra
@default@function using @event ... [Function] or as an @object using @event ... [Object]. This allows the children of @function and @object to be used as children of this entity. window.addEventListener('onchange', (evt) => {
...
})@api
@event onchange
@description
Description of event
@default: Object@description
@extra
@default
@arg
@arg?
@group
@event
@returnsfunction something (param1, param2) {
param2 = param2 || true
...
}@api
@function something
@arg param1 [String]
@arg? param2 [Boolean]
@default: @code[true]@description
@extra
@default
@arg
@arg?
@group
@event
@returns@description
@extra
@default
@group
@property
@property?
@event
@prototype
@functionconst anObject = {
prop1: true
}@api
@object anObject
@property prop1 [Boolean]
@description
The value of this property is @code[true]true @description
@extra
@default@function using @arg ... [Function] or as an @object using @arg ... [Object]. This allows the children of @function and @object to be used as children of this entity. @api
@function functionName
@collapsed false
@arg paramName [ParamType]
@description
Param Descripton@description
@extra
@default@function using @arg ... [Function] or as an @object using @arg ... [Object]. This allows the children of @function and @object to be used as children of this entity. @api
@function functionName
@collapsed false
@arg? paramName [ParamType]
@description
Param Descripton@description
@extra
@default@function entity using @property ... [Function], or as an @object using @property ... [Object]. This allows the children of @function and @object to be used as children of this entity. @api
@object objectName
@property propertyName [PropertyType]@description
@extra
@default@function entity using @property ... [Function], or as an @object using @property ... [Object]. This allows the children of @function and @object to be used as children of this entity. @api
@object objectName
@property? propertyName [PropertyType]@description
@extra
@default
@constructor
@group
@property
@property?
@event
@method
@function@api
@prototype Array
@description
The Array prototype
@constructor
@description
Create an array of @code[undefined] elements
@arg length [Number]
@description: The length of the array to create
@method fill
@description
Fill an array with values
@arg value [Any]
@description: The value to fill withundefined elements @description
@extra@function using @returns [Function] or as an @object using @returns [Object]. This allows the children of @function and @object to be used as children of this entity. css .red-background {
background: red;
}@api
@class red-background
@description
Makes the background of an element red.red-background {
background: red;
}
.red-background.blue-text {
color: blue;
}@api
@class red-background
@description
Makes the background of an element red
@extraClass blue-text
@description
Makes the text blue on red-background elementsquantum @api
@entity class
@description
Describes a css class@api
@entity groupByApi
@arg booleanrequire('quantum-api').
For information about different versions, see the Changelog @default blocks for providing default values for parameters etc. @description block like this block of text. @extra blocks inside a selection for providing information, such as code examples or additional descriptions. @group blocks inside a selection. function or object that will be used to class the header. @function by providing a header and a set of entity transforms to apply to content. const item = require('quantum-api').builders.body.item
const itemGroup = require('quantum-api').builders.body.itemGroup
const descriptions = itemGroup
const functionBuilder = item({
..., // Other options
content: [ descriptions, params, returns ]
})
module.exports = () => ({
entityTransforms: {
function: functionBuilder
}
})@function something
# Display order is determined by item, not by order in file
@returns Boolean
@arg a [String]
@description: Description goes firstType: Item for rendering an item as a different type of item when it is given a type const item = require('quantum-api').builders.body.item
const functionBuilder = item({
... // Define a function builder
})
const propertyBuilder = item({
..., // Other options
renderAsOther: { Function: functionBuilder }
})
module.exports = () => ({
entityTransforms: {
function: functionBuilder,
property: propertyBuilder
}
})@property property [String]
@property something [Function]
@arg p1 [String]'param' or ['param', 'param?'] false@changelogList entities. @changelogList basis using @groupByApi true false@changelogList basis using @reverseVisibleList true falsequantum-api module. itemGroup s of entities should be displayed in at the top-level. [
builders.body.description,
builders.body.extras,
builders.body.groups,
languages.javascript.properties,
languages.javascript.prototypes,
languages.javascript.objects,
languages.javascript.functions,
languages.css.classes,
languages.quantum.entities
][
languages.javascript(),
languages.css()
]quantum-html to define the entities that can be rendered. trueconst html = require('quantum-html')
const api = require('quantum-api')
const apiOptions = {
// Define api options here
}
const htmlOptions = {
entityTransforms: {
html: html.entityTransforms(),
api: api.entityTransforms(apiOptions) // Add the api section renderers to the page
}
}
module.exports = {
pages: '*.um',
pipeline: [
html.fileTransform(htmlOptions)
]
}@function exampleFunction
@description: Function description
@arg param1 [String]: Parameter
@arg? param1 [String]: Optional parameter
@object exampleObject
@description: Object descriptionconst html = require('quantum-html')
const api = require('quantum-api')
const apiOptions = {
// Define api options here
}
const htmlOptions = {
entityTransforms: {
html: html.entityTransforms(),
api: api.entityTransforms(apiOptions) // Add the api section renderers to the page
}
}
module.exports = {
pages: '*.um',
pipeline: [
api.fileTransform(apiOptions),
html.fileTransform(htmlOptions)
]
}@api moduleName
@function exampleFunction
@added 1.0.0
@description: Function description
@arg param1 [String]: Parameter
@arg? param2 [String]: Optional parameter
@object exampleObject
@description
Object Description
@added 2.0.0
@description
Added an example object@changelogList
@groupByApi false
@reverseVisibleList true
@process
@inline path/index.um
@version 2.0.0
@description: Version 2.0.0 changes
@version 1.0.0
@description: Version 1.0.0 changesconst version = require('quantum-version')
const api = require('quantum-api')
const html = require('quantum-html')
const apiOptions = {
// Define api options here
}
const htmlOptions = {
entityTransforms: {
html: html.entityTransforms(),
api: api.entityTransforms(apiOptions) // Add the api section renderers to the page
}
}
module.exports = {
pages: '*.um',
pipeline: [
version.fileTransform(versionOptions), // Generate versioned pages (e.g. page/1.0.0/index.html)
html.pageTransform(htmlOptions)
]
}@versionedPage
@version 1.0.0
@version 2.0.0
@api moduleName
@function exampleFunction
@added 1.0.0
@description: Function description
@arg param1 [String]: Parameter
@arg? param2 [String]: Optional parameter
@object exampleObject
@description
Object Description
@added 2.0.0
@description
Added an example objectconst dom = require('quantum-dom')
const path = require('path')
const api = require('quantum-api')
// Define the stylesheet asset we're using
const assets = [
dom.asset({
url: '/custom-language.css',
filename: path.join(__dirname, 'custom-language.css')
})
]
// Define the name of the language
const languageName = 'custom'
// Create a group of @thing entities for the @custom item
const things = api.builders.itemGroup(languageName, 'thing', 'Things')
function customDetails (selection, transformer) {
// render the param string as the header details (e.g. for '@thing something' it would be 'something')
return dom.create('div').text(selection.ps())
}
// Create the transform for the item header
const customHeader = api.builders.header('custom', customDetails)
// Create the @custom item transform
const customBuilder = api.builders.item({
class: 'api-custom', // Set the class to add to the item
header: customHeader, // Set the header renderer
content: [ api.builders.body.description, things ] // Set the content to display (and the order)
})
// Create the @thing item transform
const thingBuilder = api.builders.item({
class: 'api-thing',
header: customHeader,
content: [ api.builders.body.description ]
})
function changelogHeader (changelogHeaders) {
const entityTypes = Object.keys(changelogHeaders)
return (selection, transformer) => {
// Check if the selection has one of the changelog types
if (entityTypes.some(entityType => selection.has(entityType))) {
let current = selection
const sections = []
// Move down the tree of entries to the bottom, adding each level as a 'section'
while (entityTypes.some(entityType => current.has(entityType))) {
current = current.select(entityTypes)
const type = current.type()
const baseType = type.replace('?', '')
const section = dom.create('span')
.class(`qm-changelog-custom-${baseType}`)
// Render the header using the 'api' entity transform
.add(changelogHeaders[type](current, transformer))
sections.push(section)
}
return dom.create('span')
.class('qm-changelog-custom-header')
// Add all the built sections for the tree to the changelog header
.add(sections)
}
}
}
// Define the function that gets the custom langugae
module.exports = function customLanguage () {
const changelogHeaders = {
custom: customHeader
}
return {
assets: assets,
name: languageName,
// Export the entityTransforms we want to render with
entityTransforms: {
custom: customBuilder,
thing: thingBuilder
},
// Export the changelog options
changelog: {
// Export the entity types to look for
entityTypes: Object.keys(changelogHeaders),
// Export the function for building the changelog header
createHeaderDom: changelogHeader(changelogHeaders)
}
}
}
const html = require('quantum-html')
const api = require('quantum-api')
const customLanguage = require('./custom-language.js')
// Add the new language to the api options
const apiOptions = {
languages: [
customLanguage()
]
}
// Add the api entity transforms to htmlTransforms if they weren't there already
const htmlOptions = {
entityTransforms: {
api: api.entityTransforms(apiOptions)
}
}
// Add the fileTransform for rendering changelog content
module.exports = {
pages: '**/*.um',
pipeline: [
api.fileTransform(apiOptions),
html.fileTransform(htmlOptions)
]
}/* Change the color of the toggle and border */
.api-custom {
border-color: purple;
}
.api-custom > .qm-api-collapsible-heading .qm-api-collapsible-toggle {
background: purple;
}
.api-thing {
border-color: orange;
}
.api-thing > .qm-api-collapsible-heading .qm-api-collapsible-toggle {
background: orange;
}
@custom something
@added 1.0.0
@description
Added something
@description
Description of something
@thing thing1: Thing 1
@thing thing2: Thing 2@changelogList
@process
@inline index.um
@version 1.0.0