atomphp/atom — Issue #3: Live Documentation Proposal
Author: nerdsrescueme
Created: 2011-10-25 14:52:20+00:00
State: open

I've already begun developing our documentation system, but wanted to make a formal proposal of it.

### Live Docs

I propose that all documentation be 'live', that is... the documentation is a direct extension of the source code. There will be no central documentation repo, as the documentation is compiled (and possibly cached) at runtime.

### How

I have begun developing a core Atom feature known as "Source". Essentially, the Source library provides direct access to source code within an Atom application, or Ion. It's purpose is not to be a run-time tool for production environments, but as a secondary processor (ie. documentation, annotations, tasks to be completed once). Source will be utilized to create a just-in-time compiler for documentation based on PHPDoc style docblocks within the source code itself.

### Benefits

This will provide theme-able documentation. Enabling developers to brand their applications documentation to suit their needs, adding javascript, stylesheets and images. Since Atom is unlicensed, I would say we promote leaving a link back to Atom in the documentation, however, not make it necessary.

The developer would be able to provide their client with branded documentation for both the Atom core, as well as their own application code. Since the documentation will be JIT compiled, it will always be up-to-date within the context of the application and will update along with the code-base automatically.

### Challenges

Developing a system for utilizing docblocks. Since this will be completely custom (not relying on third party documentation programs), we will need to develop a standard for how docblocks should be created. I recommend using the conventions found with PHPDoc, and adding a bit of our own flavor.