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

phpDocumentor2 - your source matters

phpDocumentor2 - your source matters

Your source tells more about your project than you would probably think. Its structure, inline documentation and attached meta data all form a description, perhaps even a definition. phpDocumentor2 analyses your source and converts this into clearly readable and searchable piece of documentation. In this talk I want to show you how to effectively document your source.

Mike van Riel

October 07, 2012
Tweet

More Decks by Mike van Riel

Other Decks in Technology

Transcript

  1. joind.in / 7001
    phpDocumentor
    Your source matters
    Documenting with

    View Slide

  2. joind.in / 7001
    phpDocumentor
    Who am I?
    Mike van Riel

    @mvriel

    Lead Developer for
    phpDocumentor 2

    Core Developer for Cilex

    Contributor for many others

    Foster-father of 2 (dogs)

    View Slide

  3. joind.in / 7001
    phpDocumentor
    What is going to be covered?

    Documenting using DocBlocks

    What to document

    How to document

    With which aids to document

    Generating documentation with phpDocumentor2

    How to

    Templates

    View Slide

  4. joind.in / 7001
    phpDocumentor
    “Your aim should be
    self-documenting code,
    for everything else there is
    PHPDoc”

    View Slide

  5. joind.in / 7001
    phpDocumentor
    Anatomy of a DocBlock

    /** */ is a DocComment (T_DOC_COMMENT)

    A DocComment can contain a PHPDoc DocBlock

    A DocBlock can be divided in

    Short description

    Long description

    Tags

    View Slide

  6. joind.in / 7001
    phpDocumentor
    Example
    /**
    * Returns a description.
    *
    * Describes what a description would be.
    *
    * @return string
    */

    View Slide

  7. joind.in / 7001
    phpDocumentor
    We have documentation

    http://phpdoc.org/docs/latest

    Continuous Work in Progress

    Budding PSR

    https://github.com/phpDocum
    entor/phpDocumentor2/blob/d
    evelop/docs/PSR.md

    View Slide

  8. joind.in / 7001
    phpDocumentor
    Instead of talking, lets
    Demonstrate
    Disclaimer: no animals are hurt in the process,
    probably just my pride

    View Slide

  9. joind.in / 7001
    phpDocumentor
    Conclusion

    Documentation of your code is

    Simple

    Versatile

    Documenting code helps

    your design

    writing tests

    phpDocumentor uses that to
    generate high quality
    documentation

    View Slide

  10. joind.in / 7001
    phpDocumentor
    Questions?

    Please rate this talk on
    https://joind.in/7001

    More information can
    be found at:
    http://phpdoc.org

    Follow me on twitter

    @mvriel

    @phpdocumentor

    View Slide