<commit_before># Dgeni - Documentation Generator [![Build Status](https://travis-ci.org/angular/dgeni.svg?branch=master)](https://travis-ci.org/angular/dgeni)

The node.js documentation generation utility by angular.js and other projects.

## Getting started

Try out the Dgeni example project at https://github.com/petebacondarwin/dgeni-example

## Installation

You'll need node.js and a bunch of npm modules installed to use Dgeni.  Get node.js from here:
http://nodejs.org/.

In the project you want to document you install Dgeni by running:

```
npm install dgeni --save
```

This will install Dgeni and any modules that Dgeni depends upon.


## Running Dgeni

Dgeni on its own doesn't do much.  You much configure it with **Packages** that contain **Services**
and **Processors**. It is the **Processors** that actually convert your source files to
documentation files.

To the run the processors we create a new instance of `Dgeni`, providing to it an array of **Packages**
to load.  Then simply call the `generate()` method on this instance.  The `generate()` method runs the
processors asynchronously and returns a **Promise** to the generated documents.

```js
var Dgeni = require('dgeni');

var packages = [require('./myPackage')];

var dgeni = new Dgeni(packages);

dgeni.generate().then(function(docs) {
  console.log(docs.length, 'docs generated');
});
```

### Running from the Command Line

Dgeni is normally used from a build tool such as Gulp or Grunt but it does also come with a
command line tool.

If you install Dgeni globally then you can run it from anywhere:

```bash
npm install -g dgeni
dgeni some/package.js
```

If Dgeni is only installed locally then you either have to specify the path explicitly:

```bash
npm install dgeni
node_modules/.bin/dgeni some/package.js
```

or you can run the tool in an npm script:

```js
{
  ...
  scripts: {
    docs: 'dgeni some/package.js'
  }
  ...
}
```


The usage is:


```bash
dgeni path/to/mainPackage [path/to/other/packages ...] [--log level]
```

You must provide the path to one or more Dgeni Packages to load. You can, optionally, set
the logging level.


## Packages

**Services**, **Processors**, configuration values and templates are be bundled into a `Package`.  Packages
can depend upon other Packages.  In this way you can build up your custom configuration on
top of an existing configuration.

### Defining a Package

Dgeni provides a `Package` type that you instantiate.  This instance has methods to register **Services** and
**Processors**, and to configure the properties of **Processors**:

```js
var Package = require('dgeni').Package;
var myPackage = new Package('myPackage', ['packageDepencency1', 'packageDependency2']);

myPackage.processor(require('./processors/processor1'));
myPackage.processor(require('./processors/processor2'));

myPackage.factory(require('./services/service1'));
myPackage.factory(require('./services/service2'));

myPackage.config(function(processor1, service2) {
  service2.someProperty = 'some value';
  processor1.specialService = service2;
});
```


## Services

Dgeni makes significant use of **Dependency Injection (DI)** to instantiate objects.  Objects that
will be instantiated by the DI system must be provided by a **factory function**, which is registered
in a **Package**, either as a **Processor**, by `myPackage.processor(factoryFn)`, or as a **Service**,
by `myPackage.factory(factoryFn)`.

### Defining a Service

The parameters to a factory function are dependencies on other services that the DI system must find
or instantiate and provide to the factory function.

```js
module.exports = function car(function(engine, wheels) {
  return {
    drive: function() {
      engine.start();
      wheels.turn();
    }
  };
})
```

Here we have defined a `car` service, which depends upon two other services, `engine` and `wheels`
defined elsewhere.  Note that this `car` service doesn't care how and where these dependencies are
defined. It relies on the DI system to provide them when needed.

The `car` service returned by the factory function is an object containing one method, `drive()`,
which in turn calls methods on `engine` and `wheels`.



## Processors

**Processors** are **Services** that contain a `$process(docs)` method.  The processors are run
one after another in a pipeline. Each Processor takes the collection documents from the previous
Processor and manipulates it, maybe inserting new documents or adding meta data to documents that are
there already.

Processors can expose properties that tell Dgeni where in the pipeline they should be run and
how to validate the configuration of the Processor.

* `$enabled` - if set to `false` then this Processor will not be included in the pipeline
* `$runAfter` - an array of strings, where each string is the name of a Processor that must appear
**earlier** in the pipeline than this Processor
* `$runBefore` - an array of strings, where each string is the name of a Processor that must appear
**later** in the pipeline than this one
* `$validate` - a [http://validatejs.org/](http://validatejs.org/) constraint object that Dgeni uses
to validate the properties of this Processor.


### Defining a Processor

You define Processors just like you would a Service:

**myDocProcessor.js**:
```js
module.exports = function myDocProcessor(dependency1, dependency2) {
  return {
    $process(docs) { ... do stuff with the docs ... }
    $runAfter: ['otherProcessor1'],
    $runBefore: ['otherProcessor2', 'otherProcessor3'],
    $validate: {<commit_msg>docs(README): add missing function keyword to $process<commit_after># Dgeni - Documentation Generator [![Build Status](https://travis-ci.org/angular/dgeni.svg?branch=master)](https://travis-ci.org/angular/dgeni)

The node.js documentation generation utility by angular.js and other projects.

## Getting started

Try out the Dgeni example project at https://github.com/petebacondarwin/dgeni-example

## Installation

You'll need node.js and a bunch of npm modules installed to use Dgeni.  Get node.js from here:
http://nodejs.org/.

In the project you want to document you install Dgeni by running:

```
npm install dgeni --save
```

This will install Dgeni and any modules that Dgeni depends upon.


## Running Dgeni

Dgeni on its own doesn't do much.  You much configure it with **Packages** that contain **Services**
and **Processors**. It is the **Processors** that actually convert your source files to
documentation files.

To the run the processors we create a new instance of `Dgeni`, providing to it an array of **Packages**
to load.  Then simply call the `generate()` method on this instance.  The `generate()` method runs the
processors asynchronously and returns a **Promise** to the generated documents.

```js
var Dgeni = require('dgeni');

var packages = [require('./myPackage')];

var dgeni = new Dgeni(packages);

dgeni.generate().then(function(docs) {
  console.log(docs.length, 'docs generated');
});
```

### Running from the Command Line

Dgeni is normally used from a build tool such as Gulp or Grunt but it does also come with a
command line tool.

If you install Dgeni globally then you can run it from anywhere:

```bash
npm install -g dgeni
dgeni some/package.js
```

If Dgeni is only installed locally then you either have to specify the path explicitly:

```bash
npm install dgeni
node_modules/.bin/dgeni some/package.js
```

or you can run the tool in an npm script:

```js
{
  ...
  scripts: {
    docs: 'dgeni some/package.js'
  }
  ...
}
```


The usage is:


```bash
dgeni path/to/mainPackage [path/to/other/packages ...] [--log level]
```

You must provide the path to one or more Dgeni Packages to load. You can, optionally, set
the logging level.


## Packages

**Services**, **Processors**, configuration values and templates are be bundled into a `Package`.  Packages
can depend upon other Packages.  In this way you can build up your custom configuration on
top of an existing configuration.

### Defining a Package

Dgeni provides a `Package` type that you instantiate.  This instance has methods to register **Services** and
**Processors**, and to configure the properties of **Processors**:

```js
var Package = require('dgeni').Package;
var myPackage = new Package('myPackage', ['packageDepencency1', 'packageDependency2']);

myPackage.processor(require('./processors/processor1'));
myPackage.processor(require('./processors/processor2'));

myPackage.factory(require('./services/service1'));
myPackage.factory(require('./services/service2'));

myPackage.config(function(processor1, service2) {
  service2.someProperty = 'some value';
  processor1.specialService = service2;
});
```


## Services

Dgeni makes significant use of **Dependency Injection (DI)** to instantiate objects.  Objects that
will be instantiated by the DI system must be provided by a **factory function**, which is registered
in a **Package**, either as a **Processor**, by `myPackage.processor(factoryFn)`, or as a **Service**,
by `myPackage.factory(factoryFn)`.

### Defining a Service

The parameters to a factory function are dependencies on other services that the DI system must find
or instantiate and provide to the factory function.

```js
module.exports = function car(function(engine, wheels) {
  return {
    drive: function() {
      engine.start();
      wheels.turn();
    }
  };
})
```

Here we have defined a `car` service, which depends upon two other services, `engine` and `wheels`
defined elsewhere.  Note that this `car` service doesn't care how and where these dependencies are
defined. It relies on the DI system to provide them when needed.

The `car` service returned by the factory function is an object containing one method, `drive()`,
which in turn calls methods on `engine` and `wheels`.



## Processors

**Processors** are **Services** that contain a `$process(docs)` method.  The processors are run
one after another in a pipeline. Each Processor takes the collection documents from the previous
Processor and manipulates it, maybe inserting new documents or adding meta data to documents that are
there already.

Processors can expose properties that tell Dgeni where in the pipeline they should be run and
how to validate the configuration of the Processor.

* `$enabled` - if set to `false` then this Processor will not be included in the pipeline
* `$runAfter` - an array of strings, where each string is the name of a Processor that must appear
**earlier** in the pipeline than this Processor
* `$runBefore` - an array of strings, where each string is the name of a Processor that must appear
**later** in the pipeline than this one
* `$validate` - a [http://validatejs.org/](http://validatejs.org/) constraint object that Dgeni uses
to validate the properties of this Processor.


### Defining a Processor

You define Processors just like you would a Service:

**myDocProcessor.js**:
```js
module.exports = function myDocProcessor(dependency1, dependency2) {
  return {
    $process: function (docs) { ... do stuff with the docs ... }
    $runAfter: ['otherProcessor1'],
    $runBefore: ['otherProcessor2', 'otherProcessor3'],
    $validate: {
{'fraction_non_alphanumeric': 0.10364321608040201, 'fraction_numerical': 0.002871500358937545, 'mean_word_length': 4.482046237088047, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 6, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 0, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 0, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '841650', 'n_tokens_mistral': 3164, 'n_tokens_neox': 3051, 'n_words': 1388}