# The Doc Gear
, (*1)
API Documentation Generator using Markdown, (*2)
Think Natural Docs but using 100% markdown., (*3)
This project is designed to document any language that supports
the doc block comments syntax. This is what a doc block looks like:, (*4)
/**
* I am a doc block
*/
## How to Install
Installation via composer is easy:, (*5)
composer require gears/doc:* --dev
Or you may wish to install the command globally on your system:, (*6)
composer global require gears/doc:*
## Running the Command gearsdoc
Once installed you just need to run the command like so:, (*7)
/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, (*8)
## 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
syntax, inside the doc block., (*9)
### Gotchas
Make sure your doc blocks are spaced correctly,
for example the following is a bad doc block:, (*10)
/**
*foo
*/
Where as this is one is correct:, (*11)
/**
* foo
*/
Apart from that there are no other hard requirements., (*12)
However to make effective good looking documenation
with gearsdoc there are some things you need know:, (*13)
### Titles:
The first <h1> element in a doc block is considered the title for that
doc block. Obviously if the doc block does not contain a <h1> element
then we don't set the title attribute., (*14)
Here is a doc block that has a title:, (*15)
/**
* I AM THE DOC BLOCK TITLE
* ========================
* this is just normal text
*/
And here is what it looks like:, (*16)
I AM THE DOC BLOCK TITLE
this is just normal text, (*17)
### 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., (*18)
Out of the box gearsdoc will set some contexts for you. If you wish to add
your own contexts see: Property: blockContexts., (*19)
Here is a doc block with the Class context:, (*20)
/**
* Class: Baz
* ==========
*/
And the resulting bootstrap panel:, (*21)
### 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., (*22)
Here is a doc block with signature:, (*23)
/**
* I AM THE DOC BLOCK TITLE
* ========================
* this is just normal text
*/
$foo = 'bar';
And here is what it looks like:, (*24)
I AM THE DOC BLOCK TITLE
$foo = 'bar';
this is just normal text, (*25)
### 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 :), (*26)
There are basically 3 types of internal links:, (*27)
- 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:, (*28)
/**
* [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., (*29)
NOTE: There are a few working example in this page, see if you can find them., (*30)
Developed by Brad Jones - brad@bjc.id.au, (*31)
Wallogit.com
