====== The Akelos PHP Framework Documentation System ======
IMPORTANT NOTE: This document is a draft and also an editable Wiki page.
Please help us on defining the most agile approach to documenting Akelos, correcting this document or providing/clarifying ideas.
This document describes the motivation behind a custom documentation system for the [[http://www.akelos.org/|Akelos PHP Framework]].
===== Background. =====
One of the goals of Akelos is to have similar interfaces to those available at [[http://www.rubyonrails.org/|Rails]]. The main reason for this decision –others than code quality and simplicity– is to benefit form their narrative API and existing ongoing efforts in the Rails community to improve its documentation.
Changing [[http://www.rubyonrails.org/|Rails]] API documentation itself to suit the [[http://www.akelos.org/|PHP Framework]] [[http://akelos.org/|Akelos]] is a really straight forward thing to do, but the challenge comes when using de-facto standard PHP documentation systems which have different formatting rules than the ones available with Ruby’s RDOc.
[[http://api.akelos.org/|Currently Akelos]] is using [[http://www.phpdoc.org/|PHPDocumentor]] for extracting the inline documentation, but the [[http://api.akelos.org/|formatting and usability of generated documents is really poor]].
===== Proposal. =====
The [[http://www.akelos.org/|Akelos PHP Framework]] favors convention over configuration wherever is possible and that should also apply to the inline documentation.
Sticking to naming conventions we can get a coherent feeling across the code and documentation.
==== Who can edit the API documentation?. ====
This documentation should only be edited by experienced developers who are familiar with the underlying concepts and internals of Akelos.
Anyhow, we believe that opening the door for everybody to contribute to the API will benefit tremendously the community and the quality of the documents.
We need a way for achieving this contradictory duality and that is were the Akelos Documentation SYstem enters in the game.
===== The Akelos Documentation System =====
[[http://api.akelos.org|The Akelos API]] than can be edited by anyone using a wiki like system for that purpose.
The changes will be held for moderation by one of the core developers who will verify the validity of the change before adding it into the source.
==== Formatting ====
Akelos inline documentation will be formatted using [[http://daringfireball.net/projects/markdown/|Markdown]] rules.
==== Inner linking ====
Links between different functions will be in the form of Markdown links, like: [[AkActiveRecord::find|Active Record finders]] or [AkActiveRecord::find]
==== Testing the examples. ====
In order to keep the documentation up to date, the example contained on it need to have a unit test that proves its validity as the framework evolves. This continuous testing will allow us to detect documentation errors and save our users from failing due our errors.
The convention for adding documentation examples is the following:
On the file lib/AkActionView/helpers/url_helper.php:
Example:
url_for('Show posts', array('controller'=>'blog', 'action'=>'listing')); ?>
Produces:
Show posts
That is all we need to have at the inline documentation, and what is going to be rendered on the XHTML version (using syntax highlighting). The documentation system will detect that the example is PHP code and if it does not exist yet, it will generate the following test for us at tests/doc/lib/AkActionView/helpers/url_helper.php
class UrlHelperDocumentaionTestCase extends AkDocumentationTestCase{
function test_for_url_helper_example()
{
$this->assertEqual(
$url_helper->url_for('Show posts', array('controller'=>'blog', 'action'=>'listing')),
'Show posts'
);
}
}
So our only task to make this test pass is to instantiate the UrlHelper at $url_for.
This tests will be generated automatically, but they are not compulsory at this very first stage, where documenting undocumented features should be the priority number one.
If someone finds a bug in one of the examples we should allow users to help us correcting the errors by allowing them to send us an alternative unit tested example.
Only PHP blocks are considered automatically for unit testing.
=== Adding more than one example ===
Should be as simple as
Example 2:
$Post->collect($Post->find('first'), array('name','email'));
Returns:
array(‘Jane’ => ‘jane@example.com’)
==== Using inline HTML ====
Follow the instructions at the [[http://daringfireball.net/projects/markdown/syntax#html|Markdown Syntax reference]] on how to use inline HTML.
==== Conventions on return values, and parameters ====
We should not need to implicitly declare an input/return attribute types if the variable/function uses is self describing and this can be done programatically taking into account established naming conventions.
Having a method like isValid() does not need an an explanation on the return value unless there is a default return value worth documenting.
For more ambiguous cases when conventions are not sufficient we can always use JavaDoc type attributes like @param, @return….
Remember the [[http://akelos.org/Akelos_Framework_Developer_Coding_Style_Guide.pdf|Akelos PHP Framework coding style]] guide… ObjectsCamelCased, $_private_vars and so on.
==== Syntax highlighting ====
Syntax highlighting will take place automatically in these cases
* PHP: Starts with `
Javascript Example:
Ajax.request();
The parser will automatically for mat the code as Javascript.
FIXME work in progress…
===== Todo =====
* Complete this document as new conventions are being discovered
* Prepare a web based environment for editing documentation. (closed to trusted collaborators until versioning is ready).
* Reformat existing documentation and test documentation examples.
* Add versioning, Askimet spam protection and open the API to the public.
* Implement generators for creating different versions of the documentation (Offline documentation HTML/PDF, TexMate bundles, Zend IDE XML files...)
* Add support for comments and trackback support for liking to other sources with information about the subject.