# Leafdoc-generated API reference

## Command-line usage

Leafdoc includes a small command-line utility, useful when running from a console or a shell script, accepting some of the Leafdoc options. The syntax is:
leafdoc [options] [files]

### Usage example

leafdoc -t templates/pretty -c '@' --verbose -o documentation.html src/*.js

### Options

		 Option
		 Type
		 Default
		 Description

		 template
		 String
		 'templates/basic'
		 Akin to Leafdoc.templateDir

		 t

		 Alias of template

		 character
		 String
		 '🍂'
		 Akin to Leafdoc.leadingCharacter

		 c

		 Alias of character

		 verbose
		 Boolean
		 false
		 Akin to Leafdoc.verbose

		 v

		 Alias of verbose

		 output
		 String
		 undefined
		 File to write the documentation to. If left empty, documentation will be outputted to stdout instead.

		 o

		 Alias of output
Alias of output

		 json
		 Boolean
		 false
		 Write the internal JSON representation of the documentation instead of a templated HTML file.

## Leafdoc

Represents the Leafdoc parser

### Usage example

Output Leafdoc's own documentation to the console with:

var LeafDoc = require('./src/leafdoc.js');
var doc = new LeafDoc();
    doc.addFile('src/leafdoc.js');
console.log( doc.outputStr() );

### Constructor

		 Constructor
		 Description

		 new Leafdoc(<Leafdoc options> options)
		 Constructor for a new Leafdoc parser

### Options

		 Option
		 Type
		 Default
		 Description

		 templateDir
		 String
		 'templates/basic'
		 Defines which subdirectory (relative to the directory the curent JS
script is running) holds the handlebars template files for building up the HTML.

		 showInheritancesWhenEmpty
		 Boolean
		 false
		 When true, child classes/namespaces will display documentables from ancestors, even if the child class doesn't have any of such documentables.
e.g. display inherited events even if the child doesn't define any new events.

		 leadingCharacter
		 String
		 '🍂'
		 Overrides the Leaf symbol as the leading character for documentation lines.
See also setLeadingCharacter.

		 customDocumentables
		 Map
		 {}
		 A key-value map. Each pair will be passed to registerDocumentable.

		 verbose
		 Boolean
		 false
		 Set to true to display more information as files are being read.

### Methods

		 Method
		 Returns
		 Description

		 registerDocumentable(<String> name, <String> label?, <Boolean> inheritable?)
		 this
		 Registers a new documentable type, beyond the preset ones (function,
property, etc). New documentable should also not be an already used
keyword (class, namespace, inherits, etc).
When registering new documentables, make sure that there is an appropriate
template file for it.
Set label to the text for the sections in the generated docs.
inheritable parameter determines documentable can be inherited via inherits keyword in a subclass.

		 getTemplateEngine()
		 Handlebars
		 Returns handlebars template engine used to render templates.
You can use it for override helpers or register new.

		 setLeadingCharacter(<String> char)
		 this
		 In the rare case you don't want to use 🍂 as the leading character for
leaf directives, run this function with the desired character, e.g.
setLeadingCharacter('@');
The new leading character will apply only to files/dirs/strings parsed from
that moment on, so it's a good idea to call this before anything else.

		 addDir(<String> dirname, <String[]> extensions?)
		 this
		 Recursively scans a directory, and parses any files that match the
given extensions (by default .js and .leafdoc, mind the dots).
Files with a .leafdoc extension will be treated as leafdoc-only
instead of source.

		 addFile(<String> filename, <Boolean> isSource?)
		 this
		 Parses the given file using addBuffer.

		 addBuffer(<Buffer> buf, <Boolean> isSource?)
		 this
		 Parses the given buffer using addStr underneath. Set isSource to true to parse Leafdoc directives inside comment blocks. Otherwise, the whole file is interpreted as Leafdoc directives.

		 addStr(<String> str, <Boolean> isSource?)
		 this
		 Parses the given string for Leafdoc comments. The string is assumed to
be source code with comments, unless isSource is explicitly set to false.
directive.

		 outputStr()
		 String
		 Outputs the documentation to a string.
Use only after all the needed files have been parsed.

		 outputJSON()
		 String
		 Outputs the internal documentation tree to a JSON blob, without any formatting.
Use only after all the needed files have been parsed.

