DocBlox: your source matters @ #pfc11
3 likes1,373 views
DocBlox is a documentation generation application for PHP that parses source code and documentation comments to generate documentation. It supports PHP 5.3+ features and has improved performance over similar tools. DocBlox allows incremental parsing to speed up documentation regeneration when files change. Documentation is generated from docblocks in source code files using supported tags. Elements like classes inherit docblock information from their parents. Docblocks can reference other documented elements. Templates and themes customize the output documentation format and styles. Plugins will allow extending DocBlox's functionality in the future.
![Running docblox
$ docblox -d [FOLDER] -f [FILE] -t [DESTINATION]
OR
$ docblox parse -d [FOLDER] -f [FILE] -t [STAGING]
$ docblox transform -s [STAGING]/structure.xml -t [DESTINATION]](https://image.slidesharecdn.com/docbloxyoursourcematters-110918094044-phpapp02/85/DocBlox-your-source-matters-pfc11-10-320.jpg)
![Running docblox: Incremental parsing
$ docblox parse -d [FOLDER] -f [FILE] -t [STAGING]
$ docblox transform -s [STAGING]/structure.xml -t [DESTINATION]
➔ Structure file is written to a staging location
➔ Every parsing run DocBlox will know if a file has changed
● If so, re-parse
● If not, re-use
➔ Advantages:
● Parsing speed is increased
● Structure file is not distributed along with rest of documentation](https://image.slidesharecdn.com/docbloxyoursourcematters-110918094044-phpapp02/85/DocBlox-your-source-matters-pfc11-11-320.jpg)
![Running docblox: Incremental parsing
$ docblox parse -d [FOLDER] -f [FILE] -t [STAGING]
$ docblox transform -s [STAGING]/structure.xml -t [DESTINATION]
➔ Structure file is written to a staging location
➔ Every parsing run DocBlox will know if a file has changed
● If so, re-parse
● If not, re-use
➔ Advantages:
● Parsing speed is increased
● Structure file is not distributed along with rest of documentation](https://image.slidesharecdn.com/docbloxyoursourcematters-110918094044-phpapp02/85/DocBlox-your-source-matters-pfc11-12-320.jpg)
![Running docblox: Options
$ docblox –-help
-h [--help] Show this help message
-q [--quiet] Silences the output and logging
-c [--config] [STRING] Configuration filename OR "none", when this option is omitted DocBlox tries
to load the docblox.xml or docblox.dist.xml from the current working
directory
-f [--filename] STRING Comma-separated list of files to parse. The wildcards ? and * are supported
-d [--directory] STRING Comma-separated list of directories to (recursively) parse.
-t [--target] [STRING] Path where to store the generated output (optional, defaults to "output")
-e [--extensions] [STRING] Optional comma-separated list of extensions to parse, defaults to php, php3
and phtml
-i [--ignore] [STRING] Comma-separated list of file(s) and directories that will be ignored.
Wildcards * and ? are supported
-m [--markers] [STRING] Comma-separated list of markers/tags to filter, (optional, defaults
to: "TODO,FIXME")
-v [--verbose] Provides additional information during parsing, usually only needed for
debugging purposes
--title [STRING] Sets the title for this project; default is the DocBlox logo
--template [STRING] Sets the template to use when generating the output
--force Forces a full build of the documentation, does not increment existing
documentation
--validate Validates every processed file using PHP Lint, costs a lot of performance
--parseprivate Whether to parse DocBlocks tagged with @internal
--visibility [STRING] Specifies the parse visibility that should be displayed in the
documentation (comma seperated e.g. "public,protected")
--defaultpackagename [STRING] name to use for the default package. If not specified, uses "default"](https://image.slidesharecdn.com/docbloxyoursourcematters-110918094044-phpapp02/85/DocBlox-your-source-matters-pfc11-13-320.jpg)
![BONUS: Templates
➔ Skeleton can be generated using the following
command:
$ docblox theme:generate -t [PATH] -n [NAME]](https://image.slidesharecdn.com/docbloxyoursourcematters-110918094044-phpapp02/85/DocBlox-your-source-matters-pfc11-28-320.jpg)
DocBlox: your source matters @ #pfc11
- 2. Mike van Riel Lead Developer of DocBlox Technical Lead Developer for Unet B.V. Active with PHP since 2002
- 3. What is DocBlox? ➔ Documentation Generation Application (DGA) for PHP ➔ Inspired by phpDocumentor and JavaDoc ➔ Generates documentation from your source code ➔ Uses the structure and comments of your source code
- 5. Why DocBlox? ➔ Support for PHP 5.3+ features ➔ Performance, improved with up to 80% ➔ Memory usage, large projects use 100MB instead of gigabytes ➔ Active project, every month new features ● Bug fixes even more frequent ➔ QA Tool for in-source documentation
- 6. Feature DocBlox phpDocumentor Doxygen PHP 5.3+ Support Can cope with large projects Search Incremental Parsing Doctrine Annotations XML output Class inheritance diagram PDF DocBook Linking to external documentation Markup of descriptions using Markdown Latex support Parse directly from phar Secret feature
- 8. Who uses DocBlox? You?
- 9. Installation Installation via PEAR $ pear channel-discover pear.docblox-project.org $ pear channel-discover pear.michelf.com $ pear install docblox/DocBlox-beta Manual installation See http://docs.docblox-project.org/Installation.html#manual-installation
- 10. Running docblox $ docblox -d [FOLDER] -f [FILE] -t [DESTINATION] OR $ docblox parse -d [FOLDER] -f [FILE] -t [STAGING] $ docblox transform -s [STAGING]/structure.xml -t [DESTINATION]
- 11. Running docblox: Incremental parsing $ docblox parse -d [FOLDER] -f [FILE] -t [STAGING] $ docblox transform -s [STAGING]/structure.xml -t [DESTINATION] ➔ Structure file is written to a staging location ➔ Every parsing run DocBlox will know if a file has changed ● If so, re-parse ● If not, re-use ➔ Advantages: ● Parsing speed is increased ● Structure file is not distributed along with rest of documentation
- 12. Running docblox: Incremental parsing $ docblox parse -d [FOLDER] -f [FILE] -t [STAGING] $ docblox transform -s [STAGING]/structure.xml -t [DESTINATION] ➔ Structure file is written to a staging location ➔ Every parsing run DocBlox will know if a file has changed ● If so, re-parse ● If not, re-use ➔ Advantages: ● Parsing speed is increased ● Structure file is not distributed along with rest of documentation
- 13. Running docblox: Options $ docblox –-help -h [--help] Show this help message -q [--quiet] Silences the output and logging -c [--config] [STRING] Configuration filename OR "none", when this option is omitted DocBlox tries to load the docblox.xml or docblox.dist.xml from the current working directory -f [--filename] STRING Comma-separated list of files to parse. The wildcards ? and * are supported -d [--directory] STRING Comma-separated list of directories to (recursively) parse. -t [--target] [STRING] Path where to store the generated output (optional, defaults to "output") -e [--extensions] [STRING] Optional comma-separated list of extensions to parse, defaults to php, php3 and phtml -i [--ignore] [STRING] Comma-separated list of file(s) and directories that will be ignored. Wildcards * and ? are supported -m [--markers] [STRING] Comma-separated list of markers/tags to filter, (optional, defaults to: "TODO,FIXME") -v [--verbose] Provides additional information during parsing, usually only needed for debugging purposes --title [STRING] Sets the title for this project; default is the DocBlox logo --template [STRING] Sets the template to use when generating the output --force Forces a full build of the documentation, does not increment existing documentation --validate Validates every processed file using PHP Lint, costs a lot of performance --parseprivate Whether to parse DocBlocks tagged with @internal --visibility [STRING] Specifies the parse visibility that should be displayed in the documentation (comma seperated e.g. "public,protected") --defaultpackagename [STRING] name to use for the default package. If not specified, uses "default"
- 14. Configuration ➔ Stored as XML ➔ docblox.dist.xml or docblox.xml <?xml version="1.0" encoding="UTF-8" ?> <docblox> <parser> <default-package-name>DocBlox</default-package-name> <target>data/output</target> </parser> <transformer> <target>data/output</target> </transformer> <files> <directory>.</directory> <ignore>tests/*</ignore> </files> </docblox>
- 15. Writing Docblocks ➔ Docblocks are used to tag elements with meta-data ➔ Specific type of comment: /** … */ ➔ Three parts: ● Short description, one liner ● Long description, a complete description of the element ● Tags, annotations which provide additional information
- 16. Docblocks - II /** * This is a short description. * * This is a long description, which may span * multiple lines and contain {@inline} tags and * can be *styled* with `Markdown`. * * @param string $a This is the first variable. * @param Exception $b This is the second variable. * @param array $c This is the third variable. * * @return void */ function myFunction($a, Exception $b, array $c) { }
- 17. Supported elements ➔ Files ➔ Namespaces ➔ Includes & requires ➔ Classes ➔ Traits (not yet, is coming) ➔ Functions, methods and closures ➔ Properties ➔ Constants, global and class
- 18. Supported tags ➔ @abstract ➔ @ignore ➔ @since ➔ @access ➔ @internal ➔ @static ➔ @api ➔ @license ➔ @staticvar ➔ @author ➔ @link ➔ @subpackage ➔ @category ➔ @method ➔ @throws / @throw ➔ @copyright ➔ @name ➔ @todo ➔ @deprecated ➔ @package ➔ @tutorial ➔ @example ➔ @param ➔ @final ➔ @property ➔ @uses / @usedby ➔ @filesource ➔ @return ➔ @var ➔ @global ➔ @see ➔ @version
- 19. Inheritance ➔ Docblocks inherit by default (if not overridden) ● Short description ● Long description – Can be augmented using {@inheritdoc} ● Specific tags
- 20. Inheritance - Classes ➔ Methods ➔ Properties ➔ Tags ● @package ● @subpackage – if @package is the same as parent ● @version ● @copyright ● @author
- 21. Inheritance - METHODS ➔ Tags ● @param ● @return ● @throw / @throws ● @version ● @copyright ● @author
- 22. Inheritance - Properties ➔ Tags ● @var ● @version ● @copyright ● @author
- 23. Inheritance - Example class Parent { /** * Short description. * * @api * @param int $a First param. * @param string $b Second param. */ function doIt($a, $b) { .. } } class Child extends Parent { /** * Short description. * DocBlox adds this for you. * @param int $a First param. Note the missing @api tag * @param string $b Second param. */ function doIt($a, $b) { .. } }
- 24. Inheritance - @inheritdoc class Parent { /** * Short description. * * This is my long description. * * @param int $a First param. * @param string $b Second param. */ function doIt($a, $b) { .. } } class Child extends Parent { /** * Short description. * * This method adds another bit of functionality * {@inheritdoc} * * @param int $a First param. * @param string $b Second param. */ function doIt($a, $b) { .. } }
- 25. Inheritance - @inheritdoc class Parent { /** * Short description. * * This is my long description. * * @param int $a First param. * @param string $b Second param. */ function doIt($a, $b) { .. } } class Child extends Parent { /** * Short description. * * This method adds another bit of functionality * This is my long description. * * @param int $a First param. * @param string $b Second param. DocBlox adds this for you. */ function doIt($a, $b) { .. } }
- 26. References ➔ From Docblocks you can refer to other parts of the documentation using ● @uses * @uses MyNamespaceClass::function() ● @see * @see MyNamespaceClass::$property ● @link and {@link .. } * @link http://my.domain link text ● @example * @example gist:123456
- 27. BONUS: Templates ➔ Templates are a sequence of data transformations ➔ Can contain other templates ➔ May reside anywhere; even in your own project ● which is recommended for custom templates ➔ A transformation invokes a Writer
- 28. BONUS: Templates ➔ Skeleton can be generated using the following command: $ docblox theme:generate -t [PATH] -n [NAME]
- 29. BONUS: THEMES ➔ Are a collection of `views` ➔ Can be transformed to a specific output ➔ Templates can cherry pick from different themes ➔ Themes can 'use' eachother
- 30. Secret Feature
- 31. Plugins ➔ Starting with 0.15 DocBlox will support plugins ➔ Core functionality will be captured in a plugin (eat your own dog food) ➔ An easy pluggable event-based system ➔ Able to manipulate many functions in DocBlox
- 32. Plugins: invoking ➔ Add to configuration file as `plugins/plugin` element ➔ DocBlox Core plugin is assumed when nothing is defined ➔ Define path and class prefix for autoloading ➔ Can have options, added in configuration file
- 33. Plugins: Configuration <?xml version="1.0" encoding="UTF-8" ?> <docblox> ... <plugins> <plugin path="/my/path/to/plugin_folder" class_prefix="My_Plugin"> <option name="my_option"> value </option> </plugin> </plugins> ... </docblox>
- 34. Plugins - Example class DocBlox_Plugin_Core_Listener extends DocBlox_Plugin_Abstract { /** * Apply a set of behaviours to the given structure. * * @docblox-event transformer.pre-transform * * @param sfEvent $data * * @return void */ public function applyBehaviours(sfEvent $data) { … } }
- 35. Plugins - Hooks ➔ No XSL hooks to start with ➔ Limited set to start with: ● system.log, default logger ● system.debug, logging of debug messages ● parser.log, logging of parser errors ● transformer.transform.pre, adding behaviour ● transformer.transform.post, post processing of output ● reflection.docblock-extraction.post, validating docblock ● reflection.docblock.tag.export, transform tag to specialized form
- 36. Questions?
- 37. Mike van Riel mike.vanriel@naenius.com @mvriel http://blog.naenius.com http://joind.in/3661 Links ● http://www.docblox-project.org ● http://github.com/mvriel/docblox 37 / 37 What is SCRUM?