Upgrade to Pro — share decks privately, control downloads, hide ads and more …

DocBlox: your source matters @ #phpnw11

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.

Mike van Riel

October 17, 2011
Tweet

More Decks by Mike van Riel

Other Decks in Technology

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
    [email protected]
    @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