Projects / li3_docs

diff --git a/controllers/BrowserController.php b/controllers/BrowserController.php index 329f5f3..92b66af 100644 --- a/controllers/BrowserController.php +++ b/controllers/BrowserController.php @@ -12,7 +12,6 @@ use \Exception; use \DirectoryIterator; use \lithium\core\Libraries; use \lithium\analysis\Inspector; -use \li3_docs\extensions\analysis\DocExtractor; /** * This is the Lithium API browser controller. This class introspects your application's libraries, @@ -21,6 +20,18 @@ use \li3_docs\extensions\analysis\DocExtractor; class BrowserController extends \lithium\action\Controller { /** + * The `DocExtractor` class dependency, which can be replaced with a proxy file to read from + * a cache or database. + * + * @var array + */ + protected $_classes = array( + 'media' => 'lithium\net\http\Media', + 'response' => 'lithium\action\Response', + 'docExtractor' => 'li3_docs\extensions\analysis\DocExtractor' + ); + + /** * The name of the file used to document (describe) namespaces. By default, the document is read * from the directory being examined, and the contents of it represent the "docblock" for the * corresponding namespace. @@ -52,17 +63,17 @@ class BrowserController extends \lithium\action\Controller { * browsed, in which the current entity is contained. * - `'object'`: A multi-level array containing all data extracted about the * current entity. - * @link http://www.faqs.org/rfcs/rfc2396.html */ public function view() { - if (!$library = DocExtractor::library($this->request->lib)) { + $docExtractor = $this->_classes['docExtractor']; + + if (!$library = $docExtractor::library($this->request->lib)) { return $this->render('../errors/not_found'); } $name = $library['prefix'] . join('\\', func_get_args()); + $options = array('namespaceDoc' => $this->docFile); - $object = DocExtractor::get($this->request->lib, $name, array( - 'namespaceDoc' => $this->docFile - )); + $object = $docExtractor::get($this->request->lib, $name, $options); $crumbs = $this->_crumbs($object); return compact('name', 'library', 'object', 'crumbs'); } diff --git a/readme.wiki b/readme.wiki new file mode 100644 index 0000000..51c90b6 --- /dev/null +++ b/readme.wiki @@ -0,0 +1,38 @@ +The Lithium documentation plugin (Li3 Docs) is a tool for creating automatically browseable documentation of your application's codebase. In addition to simple descriptions and tables of contents, Li3 Docs allows application and code to be embedded with metadata and testable code examples to provide richer and more comprehensive documentation. + +### Documentation structure + +For generating documentation, Li3 Docs relies on PHP documentation blocks, or _docblocks_. These docblocks can appear above classes, methods, properties, etc., and contain three things: a short description, a longer description (often including usage examples), and docblock _tags_, which are denoted by an `@` symbol, followed by a keyword. A typical docblock might look something like this: + +{{{ +/** + * Contains an instance of the `Request` object with all the details of the HTTP request that + * was dispatched to the controller object. Any parameters captured in routing, such as + * controller or action name are accessible as properties of this object, i.e. + * `$this->request->controller` or `$this->request->action`. + * + * @see lithium\action\Request + * @var object + */ +public $request = null; +}}} + +This docblock documents a class property, and contains a short description and two docblock tags. The tags to be used in a docblock vary by what is being documented. A property docblock should contain a `@var` tag that describes what type of value the property holds, while methods have a series of `@param` tags and a `@return` tag. + +There are also general tags which can be added to any docblock. These include the `@see` tag, which allows you to link to another class, method or property, and the `@link` tag, which allows you to link to an arbitrary URL. + +### Markdown syntax + +Docblock descriptions are written in Markdown format, with a few conventions. Namely, any code references or identifiers should be enclosed in backticks. This includes namespaces, classes, variable names, and keywords like `true`, `false` and `null`. Extended code examples should be written enclosed in three sets of curly braces, i.e.: {{ // Code goes here }}}. + +### Code embedding + +In order to improve the testability of documented code examples, and to help ensure that code and documentation stay in sync, Li3 Docs supports a special syntax that allows code from class methods to be embedded inline inside Markdown text. Consider the following: + +{{{ +{{{ embed:lithium\tests\cases\core\EnvironmentTest::testSetAndGetCurrentEnvironment(1-3) }} } +}}} + +This will embed code from the `testSetAndGetCurrentEnvironment()` method of the `Environment` test case, from line 1 through line 3 as an inline code example in the Markdown text. This way, whenever the code changes, the tests change to match it, and the documentation stays up-to-date with what's in the test. + +Finally, since explanations and descriptions of code can fall out of sync with examples presented, Li3 Docs can be configured with a storage backend which retains hash values which represent the embedded code examples. When the underlying code changes, the hash values will fall out-of-sync, and corresponding documentation can be reviewed for accuracy. \ No newline at end of file