Lade Contributor Guide

lade

bin/lade is the main entry point. It delegates to lib/cli.coffee.

Makefile

The rules in the file Makefile facilitate extracting Lade’s documentation and providing it as input to Slate.

Assuming you have a copy of Slate in a directory ~/code/slate, you can use the following Make command.

make slateinput SLATE=~/code/slate

Module Exports

The lade module exports the CLI interface.

CLI

CLI(process.argv.slice(2), function(error) {
  if (error) {
    process.exit(1)
  }
})

Invoke Lade with the given command line arguments

Parameters

• inputArgs: array of command line arguments
• callback: function to call on completion

Result

The result of project.generate

Project

A Project represents a container that refers to input source files and output documentation files.

constructor

project = new Project root, out

Create a new Project instance.

Parameters

• root: filesystem path of directory containing input source files
• outPath: filesystem path of destination directory for output documentation files
• minLogLevel: minimum Logger level to emit

Result

A Project instance

generate

generate (error) ->
  ...

Extract output documentation from input source files

Parameters

• callback: function to call on completion

Result

None

Renderer

A Renderer handles rendering extracted documentation to destination files.

constructor

new Renderer project

Create a new Renderer instance.

Parameters

• project: a Project

Result

A Renderer instance

renderFile

renderFile data, fileInfo, done

Render given file content.

renderFile expects that data contains output destinations for its corresponding content.

Parameters

• data: source file content
• fileInfo: source file metadata
• callback: function to call on completion

Result

None

renderDocFile

renderDocFile segments, fileInfo, callback

Render given segments of documentation and code.

renderDocFile expects that segments contains output destinations for its corresponding content.

Parameters

• segments: array of Segment elements
• fileInfo: source file metadata
• callback: function to call on completion

Result

None

renderSegment

renderSegment segment, callback

Render given segment of documentation and code.

renderSegment expects that segment.targetPath contains an output destination for its corresponding content.

Parameters

• segment: a Segment
• callback: function to call on completion

Result

None

writeDocFile

writeDocFile docPath, data, callback

Write given documentation data to docPath.

Parameters

• docPath: filesystem path to output file
• data: data to write to output file
• callback: function to call on completion

Result

None

renderCompleted

renderCompleted callback

Indicate rendering completed.

Parameters

• callback: function to call on completion

Result

None

Source File Types

Refer to the user documentation for a list of supported source file types. Contributors can configure new source file types in lib/languages.coffee.

Each configured source file type has the following attributes:

Attribute	Type	Description	Required?
nameMatchers	list of strings	File name extensions	required
singleLineComment	list of strings	List of character sequences that introduce a single line comment	optional
multiLineComment	list of 3 strings	3-tuple of block comment starting character sequence, intra-block-comment line prefix, ending sequence	optional
commentsOnly	boolean	Indicates if the source file type contains only comments and no source code	optional
codeOnly	boolean	Indicates if the source file type contains only source code and no comments	optional
strictMultiLineEnd	boolean	Indicates if block comments of differing syntaxes can be nested	optional

CLIHelpers

Utilities for handling command line invocation

configureOptimist

configureOptimist opts, optionsConfig, projectConfig

Configure Optimist to provide two layers of defaults:

1. from the source code
2. from the user’s configuration file

And make --help show the resulting default values, regardless of tier.

Parameters

• opts: command line options object resulting from Optimist
• config: options configuration with source code defaults
• extraDefaults: options configuration with user’s configuration defaults

Result

Command line options object resulting from combining:

1. user command line options
2. user defaults
3. source code defaults

extractArgv

extractArgv opts, optionsConfig

Handle generated values specially, as follows.

1. Ensure list-style option values are always arrays, instead of being single values for one-element lists
2. Resolve filesystem paths

Parameters

• opts: command line options object resulting from Optimist
• config: options configuration

Result

opts.argv with the preceding transformations applied

Logger

Logger provides logging capabilities

Lade has pretty simple logging needs, and its contributors are unaware of a reasonable off-the-shelf solution that fits them without being too overbearing.

LEVELS

Lade uses the following output levels, and corresponding log line prefixes, colors, and mapping to console.log semantics.

Level	Prefix	Color	Console
TRACE	∴	grey	log
DEBUG	‡	grey	log
INFO		black	log
PASS	✓	green	log
WARN	»	yellow	error
ERROR	!	red	error

constructor

logger = new Logger minLogLevel

Create a new Logger object

Parameters

• minLevel: minimum log level to emit

Result

A Logger object

trace

trace 'A detail of interest to a developer relating to %s happened', aThing

Log given message at TRACE level

Parameters

• args: variable length argument list: a format string and corresponding placeholder values

Result

The string emitted to the corresponding stream

debug

debug 'Something of interest to a developer relating to %s happened', aThing

Log given message at DEBUG level

Parameters

• args: variable length argument list: a format string and corresponding placeholder values

Result

The string emitted to the corresponding stream

info

info 'A detail of interest to a user relating to %s happened', aThing

Parameters

• args: variable length argument list: a format string and corresponding placeholder values

Result

The string emitted to the corresponding stream

pass

pass 'Something of interest to a user relating to %s happened', aThing

Parameters

• args: variable length argument list: a format string and corresponding placeholder values

Result

The string emitted to the corresponding stream

warn

warn 'Something abnormal relating to %s happened', aThing

Parameters

• args: variable length argument list: a format string and corresponding placeholder values

Result

The string emitted to the corresponding stream

error

error 'Something failed relating to %s', aThing

Parameters

• args: variable length argument list: a format string and corresponding placeholder values

Result

The string emitted to the corresponding stream

emit

emit level, args...

Emit a log message at the given level

Parameters

• levelName: level at which to emit message given by args
• args: variable length argument list: a format string and corresponding placeholder values

Result

The string emitted to the corresponding stream

Simple Logging

Logger = require './utils/logger'
Logger.info 'Logging can be this simple'

Logger provides functions that let a caller log at a given level without creating a new Logger object.

Utils

Utility functions

regexpEscapePattern

A regular expression matching a class of regular expression metacharacters

regexpEscapeReplace

A replacement that escapes a matched character with \

regexpEscape

regexpEscape "a string"
regexpEscape ["an", "array", "of", "strings"]

Escape regular expression characters in a String, an Array of Strings or any Object having a proper toString-method

Parameters

• obj: a string, array of strings, or object having a toString method

Result

A transformed obj, in which characters in regexpEscapePattern have been escaped according to regexpEscapeReplace.

Credit

Adapted from the solution at http://blog.simonwillison.net/post/57956816139/escape

getLanguage

getLanguage file, languages

Detect the language that a given file is written in

The language is also annotated with a name property, matching the language’s key in LANGUAGES.

Parameters

• filePath: filesystem path of file containing language to detect
• languageDefinitions: filesystem path of module containing languages object

Result

Language object corresponding to source file type of file at filePath

splitSource

segments = Utils.splitSource data, language

Split data in a given language into an array of Segment objects

Parameters

• data: source text as a multi-line string
• language: Language object corresponding to the source file type of data

Result

Array of Segment objects, each containing source code or comment lines

Segment

A container to hold code lines and corresponding comment lines

Attributes

• code: array of source code lines
• comments: array of comment lines

preprocessComments

Preprocess comment Segment objects.

Extract a target path from comment front matter. Assemble the array of comment lines into a multi-line comment text string.

Input Segment objects are modified by adding targetPath and plainComments attributes.

Parameters

• segments: array of Segment objects
• project: Project to use
• callback: function to call on completion

Result

None