With the first alpha release of phpDocumentor (2.0.0a1), the new “Responsive” default template sports a new page layout, along with the useful layout improvements that the original DocBlox templates provided (which remain available) over the old phpDocumentor templates (which will retire with old phpDocumentor). Explore this new template at http://demo.phpdoc.org/Responsive/index.html.

*But what will this mean for DocBlox and phpDocumentor users?*

Old phpDocumentor is retiring.  Some bugfix effort may continue into bringing phpDocumentor 1.x to a close, but most effort going forward will be spent on 2.x.  On that 2.xeffort, you can expect monthly releases as 2.0.0 stabilizes, followed by monthly releases for new features and bug maintenance.

Existing DocBlox resources will be rebranded rather than removed, so that existing contributors can “come along for the ride” without much effort.

Let us know what you think, at #phpdocumentor on Freenode and @phpDocumentor on Twitter.

Mike van Riel (@mvriel) and Chuck Burgess (@ashnazg)

phpDoc2
is given a life anew
by DocBlox and you.

Here is the rundown of what has changed:

• Fixed an incompatibility with PHP 5.2.x
• Parse errors had the wrong line number
• Added an error code entry to the line numbers
• Added a new variable UNPREFIXED_CLASS to the External Class Documentation feature to do a URL substitution with the unprefixed class name.
• Altered the order of precedence for the external class documentation feature
• Parsing could break on certain special characters in descriptions
• Incremental processing broke due to a node import error

Some of these were old, some new but they had it be fixed fast.

Thanks for all the feedback and keep it coming!

The documentation is one of the points where DocBlox wants to excel; and in order to do this we need to write loads more of it. In the past month we have kickstarted this effort and re-arranged some of the sections and added loads of new content. You can see that at http://docs.docblox-project.org.

Below is listed some of the other things that were achieved in the past month:

• Documentation is greatly improved
• Code has been cleaned up; it is now compliant with the PEAR Coding Standards and several missing or incorrect docblocks were fixed.
• Added more validations for your docblocks:
• If an @param has no matching argument
• If an argument has no @param
• If the type of an @param mismatches with the given argument
• Added a new option: ignore-tags, with this option you can filter unwanted tags from your output
• Added a new option: hidden, with this option you can prevent DocBlox from processing files in hidden directories
• Added a new option: ignore-symlinks, whether to traverse into symlinks (default is to ignore symlinks)
• Separated Reflection into the actual parsing and the exporting of XML so that it may become possible that reflection is a separate component and other output formats may be supported in the future
• The structure file is now timestamped, which can be displayed in a template
• Properties that contained array definitions had their default shown incorrectly
• You can now output the parser output to a specific filename (instead of the default structure.xml) in addition to the old way of specifying only a folder where to send the output to.

There is more that is fixed and added but these are the highlights of the past month.

Next release: February 4th

Next release will be on February 4th, where we will try to improve the Code Coverage, documentation and solve a fair deal of the issues in the bug tracker.

Until then and thank you for using DocBlox!

• template:install task malfunctioned in 0.17.0
• Markers with special characters (such as @TODO) caused a XML processing error

These are the fixes up to this point,

Until next time!

This release also has 3 breaks with backwards compatibility related to templates; if you do not have custom templates then you are not affected by this. If you do use custom templates: please check the chapter ‘Why these changes?!’ later on in this posting.

The following changes and fixes were applies in this release:

• Templates are no longer automatically installed (except for the default template); you can install your own template using the template:install task.
• A website showcasing the available templates is now up: http://templates.docblox-project.org
• A new, more light-weight, template: Abstract. This template is intended to be a starting point for your own templates as it is more versatile and less heavy on the CSS. In time all existing templates will be based on this one.
• Performance is improved with a complete new inheritance module
• Class constants are now inherited too
• Renamed the default theme to new_black
• Removed ambiguity between themes and templates and merged the two concepts into template
• Renamed the task template theme to template (thus instead of theme:generate there is now a template:generate task)
• When specifying a template using an absolute path was the template copied to the data/themes/cache/[template_name] folder; this has changed to data/templates/[template_name]
• Added new meta-data to the template.xml for packaging: author, email, description and version, dependencies.

Why these changes?!

I want it to be easy for the user to work with DocBlox; to present as little configuration and overhead as possible. As such I discovered several naming errors:

1. Themes and Templates, while different in a technical way it was totally unclear to the user which was which. As such the most fitting name was chosen to name both and that was Template. Unfortunately this meant breaking Backward Compatibility because every template.xml file needed to be changed to point to the templates/[template_name] path instead of the themes/[theme_name] path.
2. Default template, by naming the template ‘Default’ it had to remain the default template indefinately. As such I see no other option then to radically change the default template because I want a new look. This would break backwards-compatibility and user expectancy. So now I let go of the name option and rename the template to new_black. The downside to this is that anyone who has built a template on top of the default name now has to change the references in their template.xml or XSL templates that point to the templates/default/* path to now point to templates/new_black/*.

In short

If you have a custom template you have to:

1. Update the template.xml and change every word theme into template
2. If your theme is derived from the default theme you have to update your template.xml and replace every instance of default with new_black

Documentation

I am not able to tell every aspect of these changes in this blog posting. It is just too much for that. In the upcoming month I will be writing a verbose set of documentation on templating and using templates.

Conclusion

This release has been thoroughly tested but sometimes something slips through the cracks. If you are the unlucky one to find an issue, do not hesitate to leave an issue report on Github, tweet me (@mvriel) or drop by on IRC at Freenode in the #docblox channel.

Thank you and until next month!

Features

The highlights for this release are:

• checkstyle output; Ben Selby contributed a theme which outputs the errors collected by DocBlox in checkstyle format. This enabled you to add it to Jenkins and use DocBlox more as a QA tools in addition to the generation of your documentation.
• There was a regression bug which prevented phar files from being read; this has been fixed
• Search in the sidebar was case sensitive; is not case insensitive
• Listing of @api elements in the sidebar was absent; is now re-implemented
• New command line argument –sourcecode which generates a basic syntax-highlighted source code views with each file listing
• More fine-grained control of which tags are indicated as deprecated, or which are required per element type, see http://www.soulbroken.co.uk/blog/2011/10/defining-requireddeprecated-tags-in-docblox for a more in-depth explanation.
• Formatting errors in the title were fixed
• The code behind the Class diagram has changed to work smoother and to show the full diagram at page load; thus preventing the ‘white screen’.
• And several other smaller bug fixes were done

For those of you wondering; global search has not yet been re-implemented. I am working on a new search algorithm which would help speed up search using Javascript.

In addition to all of the above have we made huge progress in reducing the amount of errors in the Coding standards, improved automated testing, added a CI bot to the #docblox channel on FreeNode and more smaller improvements.

Next version

In the previous sprint we have made a start with refactoring the inheritance component of DocBlox to speed it up and during this we found an interesting article on the fastest way to build a tree (http://tech.vg.no/2011/10/31/building-tree-structures-in-php-using-references/) which is actually one of the challenges in DocBlox when working with large projects.

We will be continuing work on this; making more performance improvements and trying to close as many issues as possible.

The date for next release will be December 4th.

Themes

DocBlox currently includes a few basic themes; of which the Default theme provides a basis on which other themes might work.

But we want more! Do you have a killer-theme? Or have you ever wanted to build one? Get in touch, build it or send it! I’d love to help you on your way or give ideas if needed.

Conclusion

Lot’s of stuff got improved but there is more to be done; and so we shall!

Have fun and see you with the next release at December 4th!

I took the opportunity to fix some other bugs so they could be released at the same time:

• Removed dependency on Markdown repository, pulled source in DocBlox’ repository and made require absolute for it.
• Attribution links in the sidebar open in the frame; changed to _top
• Improved re-usability of navigation sidebar so you can add your own items into it
• showing and hiding of elements by visibility was broken, is now fixed

Plugins offer a whole new way of working with your code’s structure and generated documentation. It enables you to add additional validations, implement specific behaviour for tags (such as linking to another location) and much more that I can’t even think of right now.

Instead of explaining what it can do I would like to refer to the documentation. Currently it is a Work in Progress but I hope to have it finished completely soon.

Features

Right! Before anything else; the highlights for this release:

• Plugins, please see the documentation for a complete explanation
• Sidebar has been replaced, a new sidebar has been introduced which reduces loading times for large projects, adds room for future improvements and more
• Expand all, collapse all and filtering functions for the files, namespaces and packages listing.
• More validations, even more error conditions are checked now thanks to @benmatselby; watch this item as it may grow in the future even more.
• A new report is introduced which tells you where deprecated elements are in your code.
• A new Table of Contents slide-out is added to the file view which can take you to your favourite function, constant or class instantly.
• Several usability improvements and bug fixes

On the downside: Search has been temporarily removed to be revised; a new location needed to be found and the performance was sub-par for the intended audience. It will return in a near future release.

Backwards compatibility break

On other feature was added which will probably not be noticed by many but causes a BC break for those who invoke DocBlox as library (for example Phing). In order to prevent any BC breakages in the future has a Bootstrap class been introduced which sets up the basis for DocBlox. The class can be found in the root of DocBlox and is called DocBlox_Bootstrap.

Please review the initialization of your implementation and replace it with a call to the `initialize` method of DocBlox_Bootstrap.

Next version

With the introduction of Plugins is DocBlox’ design becoming more and more stable and as such a month of time will be taken to improve performance, clean up the code base, increase test percentage and re-arrange functionality into their definitive plugins.

An interesting feature is intended for this period but I am not sure much time will be left for that.

The date for next release will be November 6th.

Conclusion

Good things are coming, at least: I think so.

Have fun and see you with the next release!

In release 0.14.1 have we fixed several issues that have been discovered with the release of 0.14.0:

• Firefox layout broke with some versions
• @uses was not parsed correctly when only one namespace part was provided; the system believed the XPath query to be incorrect
• defaults of parameters and CONSTANT values were not fully retrieved
• Pipe sign was missing in return type when using multiple types
• Project:list task was broken
• @version was mistakenly recognized as @Version of Doctrine
• Constant values are now more accurately displayed instead of quotes added by default
• Moved anchors so click-through would no longer end up underneath the header

The changelog of the past month shows a great deal of activity. We have received support and contributions from several people in the community, big kudos to you!

Let’s pick the top items from the list (in no specific order):

• Doctrine Annotations are recognized, their arguments parsed, styled and a link created to the Doctrine Annotation.
• A refactoring of the core components took place to make each a truly separate entity. They are bound by an EventDispatcher; which can be used by the user to tie in his or her own code! Documentation and more hooks will follow in the next months.
• Backwards compatibility break: most of DocBlox’ users won’t be affected but we changed the way the DocBlox_Parser class receives files and folders; it now uses a File container to collect all files and directories and to know which ones are ignored. If you use the DocBlox_Parser class directly, then a change is necessary.
• The way the ‘project root‘ is determined (the directory from where to look for ignored files) is changed; most won’t notice but if only 1 directory is provided then this is used as the project root, instead of the first subdirectory where a PHP file is found.
• The {@inheritdoc} inline tag can now also be used in the Short description, if used then the Long Description will also have it’s description augmented
• Support for the {@internal … }} inline tag; contents in this tag will only be shown if the –parseprivate argument is used during parsing
• Several aesthetic fixes to the class view
• New option `default-package-name` in the command line and configuration, this is used to change the package name for elements without package associated
• It is now possible to link to an external documentation using the `external-class-documentation` configuration element, you can define a class prefix and have it link to a predefined path
• The @method magic tag is now supported and those magic methods are added to the class view
• By default protected and private members are now hidden from the class view; toggle buttons in the upper right corner provide a way to filter members based on visibility or whether they are inherited.
• Properties are now also shown as inherited members

Quite a bit of other improvements and fixes have been made, to see a list please consult the CHANGELOG in the docs folder.

The upcoming month will probably see less improvements as we are going to spend time on performance optimalization, improving code coverage (60% now) and finishing the migration of the Coding Standards to PEAR. In addition several fixes are planned as some features could use some polish and updating.

I hope to see you again in the weekend of 1/2 October for release 0.15.0!

Happy documenting!