biscotto - npm Package Compare versions

doc/classes/Biscotto.html

doc/classes/Class.html

doc/classes/Doc.html

doc/classes/File.html

doc/classes/Foo.html

doc/classes/Generator.html

doc/classes/Method.html

doc/classes/Mixin.html

doc/classes/Node.html

doc/classes/Parameter.html

doc/classes/Parser.html

doc/classes/Property.html

doc/classes/Referencer.html

doc/classes/Templater.html

doc/classes/Test.html

doc/classes/TestClassDocumentation.html

doc/classes/TextBuffer.html

doc/classes/Tower/Model/Relation/HasMany/Scope.html

doc/classes/Variable.html

doc/classes/VirtualMethod.html

doc/files/theme/default/src/coffee/fuzzy.coffee.html

doc/metadata.json

src/metadata.coffee

2

doc/assets/search_data.js

		@@ -1,1 +0,1 @@
		window.searchData = [{"t":"basic_exports.coffee","p":"files/spec/visitor_templates/exports/basic_exports.coffee.html"},{"t":"foo","p":"files/spec/visitor_templates/exports/basic_exports.coffee.html#foo-file","h":"basic_exports.coffee"},{"t":"README.md","p":"README.md.html"},{"t":"LICENSE.md","p":"LICENSE.md.html"}]
		window.searchData = [{"t":"README.md","p":"README.md.html"},{"t":"LICENSE.md","p":"LICENSE.md.html"}]

495

metadata.json

		{
		"spec/visitor_templates/exports/basic_exports.coffee": {
		"objects": {
		"1": {
		"6": {
		"name": "foo",
		"bindingType": "variable",
		"type": "function",
		"paramNames": [],
		"startLineNumber": 1,
		"endLineNumber": 1,
		"startColNumber": 6,
		"endColNumber": 15
		"main": "./src/test.coffee",
		"files": {
		"./src/point.coffee": {
		"objects": {
		"11": {
		"0": {
		"type": "class",
		"name": "Point",
		"bindingType": "exports",
		"classProperties": [
		[
		24,
		15
		],
		[
		36,
		8
		]
		],
		"prototypeProperties": [
		[
		47,
		8
		],
		[
		51,
		10
		],
		[
		56,
		13
		],
		[
		60,
		7
		],
		[
		70,
		11
		],
		[
		86,
		11
		]
		],
		"doc": " Public: Represents a point in a buffer in row/column coordinates.\n\nEvery public method that takes a point also accepts a point-compatible\n{Array}. This means a 2-element array containing {Number}s representing the\nrow and column. So the following are equivalent:\n\n```coffee\nnew Point(1, 2)\n[1, 2]\n``` ",
		"range": [
		[
		11,
		0
		],
		[
		97,
		9
		]
		]
		}
		},
		"24": {
		"15": {
		"name": "fromObject",
		"bindingType": "classProperty",
		"type": "function",
		"paramNames": [
		"object",
		"copy"
		],
		"range": [
		[
		24,
		15
		],
		[
		36,
		1
		]
		],
		"doc": " Public: Convert any point-compatible object to a {Point}.\n\n* object:\n This can be an object that's already a {Point}, in which case it's\n simply returned, or an array containing two {Number}s representing the\n row and column.\n\n* copy:\n An optional boolean indicating whether to force the copying of objects\n that are already points.\n\nReturns: A {Point} based on the given object. "
		}
		},
		"36": {
		"8": {
		"name": "min",
		"bindingType": "classProperty",
		"type": "function",
		"paramNames": [
		"point1",
		"point2"
		],
		"range": [
		[
		36,
		8
		],
		[
		44,
		1
		]
		],
		"doc": " Public: Returns the given point that is earlier in the buffer. "
		}
		},
		"47": {
		"8": {
		"name": "copy",
		"bindingType": "prototypeProperty",
		"type": "function",
		"paramNames": [],
		"range": [
		[
		47,
		8
		],
		[
		51,
		1
		]
		],
		"doc": " Public: Returns a new {Point} with the same row and column. "
		}
		},
		"51": {
		"10": {
		"name": "freeze",
		"bindingType": "prototypeProperty",
		"type": "function",
		"paramNames": [],
		"range": [
		[
		51,
		10
		],
		[
		56,
		1
		]
		],
		"doc": " Public: Makes this point immutable and returns itself. "
		}
		},
		"56": {
		"13": {
		"name": "translate",
		"bindingType": "prototypeProperty",
		"type": "function",
		"paramNames": [
		"delta"
		],
		"range": [
		[
		56,
		13
		],
		[
		60,
		1
		]
		],
		"doc": " Public: Return a new {Point} based on shifting this point by the given delta,\nwhich is represented by another {Point}. "
		}
		},
		"60": {
		"7": {
		"name": "add",
		"bindingType": "prototypeProperty",
		"type": "function",
		"paramNames": [
		"other"
		],
		"range": [
		[
		60,
		7
		],
		[
		70,
		1
		]
		],
		"doc": "~Private~"
		}
		},
		"70": {
		"11": {
		"name": "splitAt",
		"bindingType": "prototypeProperty",
		"type": "function",
		"paramNames": [
		"column"
		],
		"range": [
		[
		70,
		11
		],
		[
		86,
		1
		]
		],
		"doc": "~Private~"
		}
		},
		"86": {
		"11": {
		"name": "compare",
		"bindingType": "prototypeProperty",
		"type": "function",
		"paramNames": [
		"other"
		],
		"range": [
		[
		86,
		11
		],
		[
		97,
		9
		]
		],
		"doc": " Public:\n\n* other: A {Point} or point-compatible {Array}.\n\nReturns:\n * -1 if this point precedes the argument.\n * 0 if this point is equivalent to the argument.\n * 1 if this point follows the argument. "
		}
		}
		}
		},
		"exports": 11
		},
		"exports": {}
		"./src/range.coffee": {
		"objects": {
		"0": {
		"7": {
		"name": "Grim",
		"type": "import",
		"range": [
		[
		0,
		7
		],
		[
		0,
		20
		]
		],
		"bindingType": "variable",
		"module": "grim@0.11.0"
		}
		},
		"1": {
		"8": {
		"name": "Point",
		"type": "import",
		"range": [
		[
		1,
		8
		],
		[
		1,
		24
		]
		],
		"bindingType": "variable",
		"path": "./point"
		}
		},
		"2": {
		"1": {
		"type": "import",
		"range": [
		[
		2,
		1
		],
		[
		2,
		12
		]
		],
		"bindingType": "variable",
		"path": "./helpers",
		"name": "newlineRegex",
		"exportsProperty": "newlineRegex"
		}
		},
		"3": {
		"5": {
		"name": "Fs",
		"type": "import",
		"range": [
		[
		3,
		5
		],
		[
		3,
		16
		]
		],
		"bindingType": "variable",
		"module": "fs",
		"builtin": true
		}
		},
		"17": {
		"0": {
		"type": "class",
		"name": "Range",
		"bindingType": "exports",
		"classProperties": [
		[
		21,
		16
		],
		[
		35,
		15
		],
		[
		55,
		23
		]
		],
		"prototypeProperties": [
		[
		18,
		8
		],
		[
		73,
		11
		]
		],
		"doc": " Public: Represents a region in a buffer in row/column coordinates.\n\nEvery public method that takes a range also accepts a range-compatible\n{Array}. This means a 2-element array containing {Point}s or point-compatible\narrays. So the following are equivalent:\n\n```coffee\nnew Range(new Point(0, 1), new Point(2, 3))\nnew Range([0, 1], [2, 3])\n[[0, 1], [2, 3]]\n``` ",
		"range": [
		[
		17,
		0
		],
		[
		76,
		59
		]
		]
		}
		},
		"18": {
		"8": {
		"name": "grim",
		"type": "primitive",
		"range": [
		[
		18,
		8
		],
		[
		18,
		11
		]
		],
		"bindingType": "prototypeProperty",
		"reference": {
		"position": [
		0,
		7
		]
		}
		}
		},
		"21": {
		"16": {
		"name": "deserialize",
		"bindingType": "classProperty",
		"type": "function",
		"paramNames": [
		"array"
		],
		"range": [
		[
		21,
		16
		],
		[
		35,
		1
		]
		],
		"doc": " Public: Call this with the result of {Range::serialize} to construct a new Range. "
		}
		},
		"35": {
		"15": {
		"name": "fromObject",
		"bindingType": "classProperty",
		"type": "function",
		"paramNames": [
		"object",
		"copy"
		],
		"range": [
		[
		35,
		15
		],
		[
		55,
		1
		]
		],
		"doc": " Public: Convert any point-compatible object to a {Point}.\n\n* object:\n This can be an object that's already a {Point}, in which case it's\n simply returned, or an array containing two {Number}s representing the\n row and column.\n\n* copy:\n An optional boolean indicating whether to force the copying of objects\n that are already points.\n\nReturns: A {Point} based on the given object. "
		}
		},
		"55": {
		"23": {
		"name": "fromPointWithDelta",
		"bindingType": "classProperty",
		"type": "function",
		"paramNames": [
		"startPoint",
		"rowDelta",
		"columnDelta"
		],
		"range": [
		[
		55,
		23
		],
		[
		60,
		1
		]
		],
		"doc": " Public: Returns a {Range} that starts at the given point and ends at the\nstart point plus the given row and column deltas.\n\n* startPoint:\n A {Point} or point-compatible {Array}\n* rowDelta:\n A {Number} indicating how many rows to add to the start point to get the\n end point.\n* columnDelta:\n A {Number} indicating how many rows to columns to the start point to get\n the end point.\n\nReturns a {Range} "
		}
		},
		"73": {
		"11": {
		"name": "isEqual",
		"bindingType": "prototypeProperty",
		"type": "function",
		"paramNames": [
		"other"
		],
		"range": [
		[
		73,
		11
		],
		[
		76,
		59
		]
		],
		"doc": " Public: Returns a {Boolean} indicating whether this range has the same start\nand end points as the given {Range} or range-compatible {Array}. "
		}
		}
		},
		"exports": 17
		},
		"./src/test.coffee": {
		"objects": {
		"1": {
		"0": {
		"type": "class",
		"name": "TestClass",
		"bindingType": "exports",
		"classProperties": [],
		"prototypeProperties": [],
		"doc": "~Private~",
		"range": [
		[
		1,
		0
		],
		[
		1,
		14
		]
		]
		}
		}
		},
		"exports": 1
		}
		}
		}

5

package.json

		@@ -16,3 +16,3 @@ {
		],
		"version": "2.1.4",
		"version": "2.2.0",
		"engines": {
		@@ -37,3 +37,4 @@ "node": ">=0.10.0"
		"async": ">= 0.1.22",
		"colors": "~0.6.2"
		"colors": "~0.6.2",
		"builtins": "0.0.4"
		},
		@@ -40,0 +41,0 @@ "devDependencies": {

145

README.md

		@@ -1,5 +0,7 @@
		Biscotto is a [CoffeeScript](http://coffeescript.org/) API documentation generator. The underlying architecture is based on [codo](https://github.com/coffeedoc/codo); however, this uses a variant of the excellent [TomDoc](http://tomdoc.org/) notation, instead of verbose JSDoc.
		# Biscotto

		[![Build Status](https://travis-ci.org/atom/biscotto.png?branch=master)](https://travis-ci.org/atom/biscotto)

		Biscotto is a tool for generating [CoffeeScript](http://coffeescript.org/) documentation. The underlying architecture was based on [codo](https://github.com/coffeedoc/codo); however, this project uses a variant of the excellent [TomDoc](http://tomdoc.org/) notation, instead of the more verbose JSDoc. It also has many more niceties.

		## Features
		@@ -10,22 +12,19 @@
		* Intermediate JSON output to transform into any output
		* Can generate a metadata blob for more advanced usage ([see below for more information](#metadata-generation))

		## Comment Parsing
		## Installing

		The following section outlines how comments in your files are processed.
		``` bash
		npm install biscotto
		```

		### TomDoc
		## Comment parsing with TomDoc

		API documentation should be written in the [TomDoc](http://tomdoc.org/)
		notation. Originally conceived for Ruby, TomDoc lends itself pretty nicely to
		Coffeescript. There are some slight changes in the parse rules to match
		Coffeescript. Briefly, here's a list of how you should format your
		documentation.
		API documentation is written in the [TomDoc](http://tomdoc.org/) notation. Originally conceived for Ruby, TomDoc lends itself pretty nicely to CoffeeScript.

		There are some slight changes in the parse rules to match CoffeeScript. Briefly, here's a list of how you should format your documentation.

		#### Visibility

		Every class and method should start with one of three phrases: `Public:`,
		`Internal:`, and `Private:`. During the documentation generation process, you
		can flag whether or not to include Internal and Private members via the options
		passed in. If you don't have one of these status indicators, Biscotto will assume the
		global visibility (more on this below).
		Every class and method should start with one of three phrases: `Public:`, `Internal:`, and `Private:`. During the documentation generation process, you can flag whether or not to include Internal and Private members via the options passed in. If you don't have one of these status indicators, Biscotto will assume the global visibility (more on this below).

		@@ -68,5 +67,3 @@ ```coffeescript

		The examples section must start with the word "Examples" on a line by itself. The
		next line should be blank. Every line thereafter should be indented by two spaces
		from the initial comment marker:
		The examples section must start with the word "Examples" on a line by itself. The next line should be blank. Every line thereafter should be indented by two spaces from the initial comment marker:

		@@ -92,4 +89,3 @@ ``` coffeescript

		When returning from a method, your line must start with the word `Returns`.
		You can list more than one `Returns` per method by separating each type on a different line.
		When returning from a method, your line must start with the word `Returns`. You can list more than one `Returns` per method by separating each type on a different line.

		@@ -117,4 +113,3 @@ ```coffeescript

		Biscotto comments are parsed for references to other classes, methods, and mixins, and are automatically
		linked together.
		Biscotto comments are parsed for references to other classes, methods, and mixins, and are automatically linked together.

		@@ -130,4 +125,3 @@ There are several different link types supported:

		As an added bonus, default JavaScript "types," like String, Number, Boolean, e.t.c.,
		have automatic links generated to [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript).
		As an added bonus, wrapping default JavaScript types--like `{String}`, `{Number}`, `{Boolean}` etc.--have links automatically generated to [MDN](https://developer.mozilla.org/en-US/docs/Web/JavaScript).

		@@ -149,7 +143,5 @@ Here's an example of using links:

		Note: reference resolution does not take place within code blocks.

		#### Status Blocks

		As noted above, classes and methods can be `Public,` `Private`, or `Internal`.
		Classes and methods can be marked as `Public,` `Private`, or `Internal`.

		@@ -162,7 +154,5 @@ You can flag multiple methods in a file with the following syntax:

		That will mark every method underneath that block as `Public`. You can follow the
		same notion for `Internal` and `Private` as well.
		That will mark every method underneath that block as `Public`. You can follow the same notion for `Internal` and `Private` as well.

		You can have as many block status flags as you want. The amount of `#`s must be at
		least three, and you can have any text inside the block you want. For example:
		You can have as many block status flags as you want. The amount of `#`s must be at least three, and you can have any text inside the block you want (for your own information). For example:

		@@ -173,4 +163,3 @@ ```coffee

		If you explicitly specify a status for a method within a block, the status is respected.
		For example:
		If you explicitly specify a status for a method within a block, the status is respected. For example:

		@@ -191,4 +180,3 @@

		If you're writing methods that do the exact same thing as another method, you can
		choose to copy over the documentation via _delegation_. For example:
		If you're writing methods that do the exact same thing as another method, you can choose to copy over the documentation via a _delegation_. For example:

		@@ -208,4 +196,3 @@ ```coffee

		`delegatedMethod` has the same arguments, return type, and documentation as
		`delegatedRegular`. You can also choose to delegate to a different class:
		`delegatedMethod` has the same arguments, return type, and documentation as `delegatedRegular`. You can also choose to delegate to a different class:

		@@ -217,26 +204,23 @@ ```coffee

		Classes that are delegated should still set their own statuses. For example, even though
		`Another.Class@somewhere` is Public, `delegatedMethod` is still marked as `Private`.
		The same documentation remains.
		Classes that are delegated should still set their own statuses. For example, even though `Another.Class@somewhere` is Public, `delegatedMethod` is still marked as `Private`. The same documentation remains.

		#### Defaults

		Unlike TomDoc, there is no notation for `default` values. Biscotto will take care of it for you.
		Unlike TomDoc, there is no additional notation for `default` values. Biscotto will take care of it for you, because it parses the CoffeeScript source and understands default values.

		## More Examples

		For more technical examples, peruse the [spec](./spec) folder, which contains all
		the tests for Biscotto.
		For more technical examples, peruse the [spec](./spec) folder, which contains all the tests for Biscotto.

		## Generate
		## Generating and serving HTML

		After the installation, you will have a `biscotto` binary that can be used to generate the documentation recursively for all CoffeeScript files within a directory.
		After installing Biscotto, you'll have a `biscotto` binary that can be used to generate the documentation recursively for all CoffeeScript files within a directory.

		To view a list of commands, type

		```bash
		``` bash
		$ biscotto --help
		```

		Biscotto wants to be smart and tries to detect the best default settings for the sources, the readme, the extra files, and
		Biscotto wants to be smart and tries to detect the best default settings for the sources, the README, any extra files, and
		the project name, so the above defaults may be different on your project.
		@@ -261,12 +245,6 @@

		Put each option flag on a separate line, followed by the source directories or files, and optionally any extra file that
		should be included into the documentation separated by a dash (`-`). If your extra file has the extension `.md`, it'll
		be rendered as Markdown.
		Put each option flag on a separate line, followed by the source directories or files, and optionally any extra file that should be included into the documentation separated by a dash (`-`). If your extra file has the extension `.md`, it'll be rendered as Markdown.

		### Gulp-Biscotto
		### Website keyboard navigation

		If you want use Biscotto with [Gulp](https://gulpjs.com), see [gulp-biscotto](https://github.com/adam-lynch/gulp-biscotto).

		## Keyboard navigation

		You can quickly search and jump through the documentation by using the fuzzy finder dialog:
		@@ -297,2 +275,59 @@

		## Gulp-Biscotto

		If you want to use Biscotto with [Gulp](https://gulpjs.com), see [gulp-biscotto](https://github.com/adam-lynch/gulp-biscotto).

		## Metadata generation

		You can use Biscotto to generate a complete JSON representation of your Node.js module. Simply pass in the `--metadata` flag and the path to your top-level module directory (where you keep your package.json).

		``` bash
		biscotto --metadata ./path/to/module
		```

		Metadata generation should be considered an "advanced" way of using Biscotto. By generating metadata, Biscotto itself doesn't provide a way to turn it into HTML or interpret the comments in any way. It relies solely on the existing CoffeeScript AST. It allows for greater consumption and flexibility, however, because it traverses over the entire module.

		You can find an example of the sort of metadata generated by [looking at the test suite](./spec/metadata_templates/test_package/test_metadata.json).

		In (very) brief, take a look at this example:

		``` json
		"objects": {
		"3": {
		"0": {
		"type": "class",
		"name": "TextBuffer",
		"classProperties": [
		[
		4,
		10
		]
		],
		"doc": " Public: A mutable text container with undo/redo support and the ability to\nannotate logical regions in the text.\n\n ",
		}
		},
		"4": {
		"10": {
		"name": "prop2",
		"type": "primitive",
		"range": [
		[
		4,
		10
		],
		[
		4,
		14
		]
		],
		"bindingType": "classProperty"
		}
		}
		}
		```

		Items are indexed by their row numbers, followed by thier column numbers. The idea is that you can traverse all along the metadata blob by simply following the location references.

		For a deeper understanding of the syntax and rationale, see the original proposal at [issue #43](https://github.com/atom/biscotto/issues/43)

		## License
		@@ -302,3 +337,3 @@

		Copyright (c) 2013 Garen J. Torikian
		Copyright (c) 2014 Garen J. Torikian

		@@ -305,0 +340,0 @@ Permission is hereby granted, free of charge, to any person obtaining

doc/class_index.html