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 object1
javascript
@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
@returns
function 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
@function
const 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 with
undefined
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 elements
quantum
@api
@entity class
@description
Describes a css class
@api
@entity groupByApi
@arg boolean
require('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 first
Type: 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
false
quantum-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. true
const 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 description
const 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 changes
const 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 object
const 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