DocBlox: your source matters @ #phpnw11

These are the slides for the talk 'DocBlox: your source matters' as given at the PHP Northwest Conference 2011 in Manchester (#phpnw11).
In this talk I have shown the basic operation of DocBlox and how to write DocBlocks in PHP, including tips and pointers to get the most out of it.

Transcript

1. DocBlox
   Your source matters
   

   View Slide

2. 2011/10/08 2
   Mike van Riel
   Lead Developer of DocBlox
   Technical Lead Developer for Unet B.V.
   Active with PHP since 2002
   

   View Slide

3. 2011/10/08 3
   What is DocBlox?
   ➔
   Documentation Generation Application (DGA) for PHP
   ➔
   Generates API documentation
   ➔
   Uses the structure and comments of your source code
   ➔
   Inspired by phpDocumentor and JavaDoc
   

   View Slide

4. 2011/10/08 4
   

   View Slide

5. 2011/10/08 5
   Why DocBlox?
   ➔
   Support for PHP 5.3+ features
   ➔
   Performance, improved with up to 80%
   ➔
   Memory usage, no more gigabytes
   ➔
   Active project, every month new features
   ●
   Bug fixes even more frequent
   ➔
   QA Tool for in-source documentation
   

   View Slide

6. 2011/10/08 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
   Checkstyle output of violations (since 0.16.0)
   Latex support
   Parse directly from phar
   Plugins
   

   View Slide

7. 2011/10/08 7
   Who uses DocBlox?
   

   View Slide

8. 2011/10/08 8
   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
   Has become obsolete with DocBlox 0.15.1
   

   View Slide

9. 2011/10/08 9
   Running docblox
   $ docblox -d [FOLDER] -f [FILE] -t [DESTINATION]
   $ docblox parse -d [FOLDER] -f [FILE] -t [STAGING]
   $ docblox transform -s [STAGING]/structure.xml -t [DESTINATION]
   OR
   

   View Slide

10. 2011/10/08 10
    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
    

    View Slide

11. 2011/10/08 11
    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"
    

    View Slide

12. 2011/10/08 12
    Configuration
    ➔
    Stored as XML
    ➔
    docblox.dist.xml or docblox.xml
    
    
    
    DocBlox
    data/output
    
    
    data/output
    
    
    .
    tests/*
    
    
    

    View Slide

13. 2011/10/08 13
    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
    

    View Slide

14. 2011/10/08 14
    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)
    {
    }
    

    View Slide

15. 2011/10/08 15
    Supported elements
    ➔
    Files
    ➔
    Namespaces
    ➔
    Includes & requires
    ➔
    Classes
    ➔
    Traits (not yet, is coming)
    ➔
    Functions, methods and closures
    ➔
    Properties
    ➔
    Constants, global and class
    

    View Slide

16. 2011/10/08 16
    Supported tags
    ➔
    @abstract
    ➔
    @access
    ➔
    @api
    ➔
    @author
    ➔
    @category
    ➔
    @copyright
    ➔
    @deprecated
    ➔
    @example
    ➔
    @final
    ➔
    @filesource
    ➔
    @global
    ➔
    @ignore
    ➔
    @internal
    ➔
    @license
    ➔
    @link
    ➔
    @method
    ➔
    @name
    ➔
    @package
    ➔
    @param
    ➔
    @property
    ➔
    @return
    ➔
    @see
    ➔
    @since
    ➔
    @static
    ➔
    @staticvar
    ➔
    @subpackage
    ➔
    @throws / @throw
    ➔
    @todo
    ➔
    @tutorial
    ➔
    @uses / @usedby
    ➔
    @var
    ➔
    @version
    

    View Slide

17. 2011/10/08 17
    Inheritance
    ➔
    Docblocks inherit by default (if not overridden)
    ●
    Short description
    ●
    Long description
    – Can be augmented using {@inheritdoc}
    ●
    Specific tags
    

    View Slide

18. 2011/10/08 18
    Inheritance - Classes
    ➔
    Methods
    ➔
    Properties
    ➔
    Tags
    ●
    @package
    ●
    @subpackage
    – if @package is the same as parent
    ●
    @version
    ●
    @copyright
    ●
    @author
    

    View Slide

19. 2011/10/08 19
    Inheritance - METHODS
    ➔
    Tags
    ●
    @param
    ●
    @return
    ●
    @throw / @throws
    ●
    @version
    ●
    @copyright
    ●
    @author
    

    View Slide

20. 2011/10/08 20
    Inheritance - Properties
    ➔
    Tags
    ●
    @var
    ●
    @version
    ●
    @copyright
    ●
    @author
    

    View Slide

21. 2011/10/08 21
    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 {
    function doIt($a, $b) { .. }
    }
    DocBlox adds this for you.
    Note the missing @api tag
    /**
    * Short description.
    *
    * @param int $a First param.
    * @param string $b Second param.
    */
    

    View Slide

22. 2011/10/08 22
    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 {
    function doIt($a, $b) { .. }
    }
    /**
    * Short description.
    *
    * This method adds another bit of functionality
    * {@inheritdoc}
    *
    * @param int $a First param.
    * @param string $b Second param.
    */
    

    View Slide

23. 2011/10/08 23
    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 {
    function doIt($a, $b) { .. }
    }
    /**
    * 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.
    

    View Slide

24. 2011/10/08 24
    References
    ➔
    From Docblocks you can refer to other parts of
    the documentation using
    ●
    @uses
    ●
    @see
    ●
    @link and {@link .. }
    ●
    @example
    * @uses \My\Namespace\Class::function()
    * @see \My\Namespace\Class::$property
    * @link http://my.domain link text
    * @example gist:123456
    

    View Slide

25. 2011/10/08 25
    Plugins
    ➔
    Core functionality is captured in a plugin (eat
    your own dog food)
    ➔
    Easy, pluggable event-based system
    ➔
    Can manipulate many functions in DocBlox
    ➔
    Add your own Transformation Writers
    

    View Slide

26. 2011/10/08 26
    Plugins: invoking
    ➔
    Add to configuration file as `plugins/plugin`
    element
    ➔
    DocBlox Core plugin is assumed when nothing
    is defined
    ➔
    Autoloading is set up by DocBlox
    ➔
    Can have options, added in configuration file
    

    View Slide

27. 2011/10/08 27
    Plugins: Configuration
    
    
    ...
    
    
    
    value
    
    
    
    ...
    
    

    View Slide

28. 2011/10/08 28
    Plugins: Creating
    ➔
    Skeleton can be generated using the following
    command:
    $ docblox plugin:generate -t [PATH] -n [NAME]
    

    View Slide

29. 2011/10/08 29
    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)
    {
    …
    }
    }
    

    View Slide

30. 2011/10/08 30
    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
    

    View Slide

31. 2011/10/08 31
    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
    

    View Slide

32. 2011/10/08 32
    BONUS: Templates
    ➔
    Skeleton can be generated using the following
    command:
    $ docblox theme:generate -t [PATH] -n [NAME]
    

    View Slide

33. 2011/10/08 33
    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
    

    View Slide

34. 2011/10/08 34
    The (NEAR?) future
    ➔
    Plugin and theme repository
    ➔
    Tasks to package and upload themes and
    plugins
    ➔
    Support for PHP 5.4
    ➔
    Improved tag support
    ➔
    More output formats (DocBook, PDF, etc)
    

    View Slide

35. 2011/10/08 35
    Questions?
    

    View Slide

36. 2011/10/08 36
    What is SCRUM?
    Mike van Riel
    mike.vanriel@naenius.com
    @docblox
    @mvriel
    http://blog.naenius.com
    Links
    ●
    http://www.docblox-project.org
    ●
    http://github.com/mvriel/docblox
    36 / 36
    http://joind.in/3598
    http://blog.naenius.com
    

    View Slide