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.

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