PHPackages                             gears/doc - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [API Development](/categories/api)
4. /
5. gears/doc

AbandonedArchivedLibrary[API Development](/categories/api)

gears/doc
=========

API Documentation Generator using Markdown

v0.1.2(11y ago)021MITJavaScript

Since Nov 6Pushed 11y ago1 watchersCompare

[ Source](https://github.com/phpgearbox/doc)[ Packagist](https://packagist.org/packages/gears/doc)[ Docs](https://github.com/phpgearbox/doc)[ RSS](/packages/gears-doc/feed)WikiDiscussions master Synced 1mo ago

READMEChangelogDependencies (13)Versions (3)Used By (0)

The Doc Gear
============

[](#the-doc-gear)

---

[![Build Status](https://camo.githubusercontent.com/8dd7f11c0704d3c4100d7aba5be8a7efef66bcedbf6da773b988f1e0d754e341/68747470733a2f2f7472617669732d63692e6f72672f70687067656172626f782f646f632e7376673f6272616e63683d6d6173746572)](https://travis-ci.org/phpgearbox/doc)[![Latest Stable Version](https://camo.githubusercontent.com/aff3d1671a350f6425acc1b09e71c9062fe6ff1d28f47de99bc4074ae0cef054/68747470733a2f2f706f7365722e707567782e6f72672f67656172732f646f632f762f737461626c652e737667)](https://packagist.org/packages/gears/doc)[![Total Downloads](https://camo.githubusercontent.com/ab8208b9f96dcfc06f6eca7fb63b69ce4cc3ccb75995da2d0aa2c5c1427e952b/68747470733a2f2f706f7365722e707567782e6f72672f67656172732f646f632f646f776e6c6f6164732e737667)](https://packagist.org/packages/gears/doc)[![License](https://camo.githubusercontent.com/1b52c2dc2ec15b54e057ddc6d4d08860e3b4cd848b7d71242b87ba0369c67724/68747470733a2f2f706f7365722e707567782e6f72672f67656172732f646f632f6c6963656e73652e737667)](https://packagist.org/packages/gears/doc)

**API Documentation Generator using Markdown**

Think [Natural Docs](http://www.naturaldocs.org/) but using 100% markdown.

This project is designed to document any language that supports the doc block comments syntax. This is what a doc block looks like:

```
/**
 * I am a doc block
 */

```

How to Install
--------------

[](#how-to-install)

---

Installation via composer is easy:

```
composer require gears/doc:* --dev

```

Or you may wish to install the command globally on your system:

```
composer global require gears/doc:*

```

Running the Command gearsdoc
----------------------------

[](#running-the-command-gearsdoc)

---

Once installed you just need to run the command like so:

```
/location/to/gearsdoc \
    --input="/the/path/to/your/source/code" \
    --output="/the/path/to/where/you/want/the/generated/docs/to/go"

```

There are many more options, either just use the `--help`option while at the terminal. Or have a look at: [Method: configure](Console/Commands/Generate.php)

Writing Doc Blocks for gearsdoc
-------------------------------

[](#writing-doc-blocks-for-gearsdoc)

---

At a basic level to write a doc block that *gearsdoc* can parse and understand all you need to do is use the [Markdown](http://en.wikipedia.org/wiki/Markdown)syntax, inside the doc block.

### Gotchas

[](#gotchas)

---

Make sure your doc blocks are spaced correctly, for example the following is a bad doc block:

```
/**
 *foo
 */

```

Where as this is one is correct:

```
/**
 * foo
 */

```

**Apart from that there are no other hard requirements.**

However to make effective good looking documenation with *gearsdoc* there are some things you need know:

### Titles:

[](#titles)

---

The first `` element in a doc block is considered the title for that doc block. Obviously if the doc block does not contain a `` element then we don't set the title attribute.

Here is a doc block that has a title:

```
/**
 * I AM THE DOC BLOCK TITLE
 * ========================
 * this is just normal text
 */

```

And here is what it looks like:

###  I AM THE DOC BLOCK TITLE

[](#i-am-the-doc-block-title)

this is just normal text

### Contexts:

[](#contexts)

---

A context is simply a CSS class that we apply to each bootstrap panel that gets generated. The context is determined by the **title** thus if there is no title there is no context.

Out of the box *gearsdoc* will set some contexts for you. If you wish to add your own contexts see: [Property: blockContexts](Generator.php).

Here is a doc block with the *Class* context:

```
/**
 * Class: Baz
 * ==========
 */

```

And the resulting bootstrap panel:

###  Class: Baz

[](#class-baz)

### Signatures:

[](#signatures)

---

The very next line after a doc block is what we call the signature. It is usally the code that defines a class, function, method or property. But it can be anything at all. If the line is blank then that doc block will not have a sigature associated with it.

Here is a doc block with signature:

```
/**
 * I AM THE DOC BLOCK TITLE
 * ========================
 * this is just normal text
 */
$foo = 'bar';

```

And here is what it looks like:

###  I AM THE DOC BLOCK TITLE

[](#i-am-the-doc-block-title-1)

```
$foo = 'bar';
```

this is just normal text

### Internal Links:

[](#internal-links)

---

I am really very happy with this feature. Being able to link to various parts of code in your doc blocks is invaluable. For example being able to link to the exact line of code that consumes a class property... priceless :)

There are basically 3 types of internal links:

- A link that references a doc block title.
- A link that references a doc block signature.
- A link that references a particular line of code.

Lets have some examples:

```
/**
 * [Method: Foo](#)
 * [private function Foo()](#)
 * [$this->foo = 'bar';](#)
 */

```

The pound (`#`) denotes the file that we will find the reference in. If the reference is in the same file as the link then just leave the pound as is.

> NOTE: There are a few working example in this page, see if you can find them.

---

Developed by Brad Jones -

###  Health Score

24

—

LowBetter than 32% of packages

Maintenance20

Infrequent updates — may be unmaintained

Popularity6

Limited adoption so far

Community7

Small or concentrated contributor base

Maturity54

Maturing project, gaining track record

 Bus Factor1

Top contributor holds 100% of commits — single point of failure

How is this calculated?**Maintenance (25%)** — Last commit recency, latest release date, and issue-to-star ratio. Uses a 2-year decay window.

**Popularity (30%)** — Total and monthly downloads, GitHub stars, and forks. Logarithmic scaling prevents top-heavy scores.

**Community (15%)** — Contributors, dependents, forks, watchers, and maintainers. Measures real ecosystem engagement.

**Maturity (30%)** — Project age, version count, PHP version support, and release stability.

###  Release Activity

Cadence

Every ~0 days

Total

3

Last Release

4208d ago

### Community

Maintainers

![](https://www.gravatar.com/avatar/2b476564958ffc91db5580080738e529644f820bdfec6a6c4d397f9c5da45065?d=identicon)[brad-jones](/maintainers/brad-jones)

---

Top Contributors

[![brad-jones](https://avatars.githubusercontent.com/u/2754772?v=4)](https://github.com/brad-jones "brad-jones (9 commits)")

---

Tags

apidocumentationgeneratormarkdown

###  Code Quality

TestsPHPUnit

### Embed Badge

![Health badge](/badges/gears-doc/health.svg)

```
[![Health](https://phpackages.com/badges/gears-doc/health.svg)](https://phpackages.com/packages/gears-doc)
```

###  Alternatives

[phpdocumentor/phpdocumentor

Documentation Generator for PHP

4.4k3.1M878](/packages/phpdocumentor-phpdocumentor)[apigen/apigen

PHP source code API generator.

2.2k627.9k225](/packages/apigen-apigen)[binarytorch/larecipe

Generate gorgeous recipes for your Laravel applications using MarkDown

2.5k2.7M16](/packages/binarytorch-larecipe)[crada/php-apidoc

Generate documentation for php API based application. No dependency. No framework required.

259206.9k2](/packages/crada-php-apidoc)[pronamic/wp-documentor

Documentation Generator for WordPress.

6529.8k5](/packages/pronamic-wp-documentor)

PHPackages © 2026

[Directory](/)[Categories](/categories)[Trending](/trending)[Changelog](/changelog)[Analyze](/analyze)