Even though I installed the latest GraphViz through PEAR Docblox keeps saying this:

Fatal error: Class 'Image_GraphViz' not found in C:\docblox\src\DocBlox\Transformer\Writer\Graph.php on line 137

C:\wamp\bin\php\php5.3.1>php pyrus.phar list-packages
Pyrus version 2.0.0a3 SHA-1: BE7EA9D171AE3873F1BBAF692EEE9165BB14BD5D
Using PEAR installation found at C:\wamp\bin\php\php5.3.1
Listing installed packages [C:\wamp\bin\php\php5.3.1]:
[channel pear.php.net]:
 Image_GraphViz

Some projects do not use File level DocBlocks; we would want to disable the error that a parsing error has occurred in this situation. Sometimes a vendor library is included in the documentation generation but should all errors related to invalid DocBlock be ignored because the developer does not want to maintain this library himself and the error pollute his own working stack.

Note: there is currently no 'centralized' system to track these kind of errors; they are now thrown by logging a WARN, ERR or CRIT. A more intelligent analysis result handling system should be added which is finetunable.

During research we have come to the conclusion to use the same configuration format as is used by PHP_CodeSniffer and be able to (re)define entire rulesets. The following tasks need to be completed

• Write technical specification for this feature
• Create Ruleset and Rule objects
• Create a pre-defined 'Default' Ruleset
• Create a pre-defined Ruleset without File DocBlock validation (often requested feature)
• Load a Ruleset from the Configuration file
• Load a Ruleset directly from a 'ruleset.xml' file
• A Ruleset may refer/include another ruleset
• When including another ruleset specific Rules may be excluded from being enabled
• Only load/enable validators that have a violation that matches one of the Rules in a Ruleset
• When executing validators, only register violations that matches one of the Rules in a Ruleset
• When executing validators, override loglevel with severity in rule
• Add support for silencing validators for specific folders
• Re-enable support for the Deprecated and Required validator
• Add support for validating only specific folders
• Allow 'properties' to be passed to validators to change their behavior

This story is also a prerequisite for #1421

If the parser detects that the version number differs a minor from the previous it requires you to do a full re-parse; the transformer should do a similar check and not transform at all if the minor version number differs

The class overview should show a small class diagram which details all parents and all children of the current class.

the current best practice is that you store your phpunit default config as phpunit.xml.dist and if you need to override your settings in the build environment, you can use phpunit.xml for that, because it has higher precedence.
so please rename the phpunit.xml to phpunit.xml.dist

Tyrael

The method listing in the class section becomes badly readable when there are too many methods; as demonstrated here: http://t.co/txDP46U

Use XHPRof to identify pieces of code which can be accelerated

docblox.config.xml is not present in my root folder of DocBlox (v 0.9.0-0)

-c [--config] [STRING]     Configuration filename, if none is given the defaults of the docblox.config.xml in the root of DocBlox is used

The structure.xml file currently does not have an XML schema, nor does the config. This means that it is less predictable for people how to use the xml files.
See kore-nordmann.de/blog/0104_generating_xml_schemas_from_xml.html for generating schemas.

XSL has a steep learning curve and it might be easier for people to implement additional pages using Twig; this would probably be slower to process but easier to make for those interested in ease over speed.

Tested with PHP 5.2.6-1+lenny9

DocBlox parser version 0.7.1-DEV
./bin/parse.php -d somedir

Fatal error: Undefined class constant 'SKIP_DOTS' in DocBlox/Arguments.php on line 166

( RecursiveDirectoryIterator::SKIP_DOTS )

Fatal error: Class 'finfo' not found in /ajut/sites/hosting/lp/www/Docblox/Docblox/DocBlox/Reflection/File.php on line 40

etc.

Let's assume the folllowing architecture:

DocbloxDir/
ProjectsDir/
ProjectsDir/ProjectA/
ProjectsDir/ProjectA/src/
ProjectsDir/ProjectA/doc/

If you stand in ProjectA and give the following command
<path_to>/DocbloxDir/bin/prarse.php -d src -t doc

The log directory is searched relative to the directory you're at. In this situation, the ProjectA directory.

First, thanks very much for creating a PEAR package for Docblox. Unfortunately, the files overlap with Zend's PEAR package, which I use. It would be nice if dependencies were split up - you could rely on Zend's pear package, and perhaps even break out the markdown dependency.

Cheers,

Bill

It might be nice to implement a (set of) pages where you can see an overview of everything that is added per version using the @SInCE tag.

We want phpDocumentor to show Reference Documentation as well as API Documentation.

Goal

The goal for this item is to provide a, simple but robust, implementation to generate reference documentation.

Background

phpDocumentor 1 provided the user with the ability to generate tutorials; which were in essence DocBook documents following a rigid directory structure.

For phpDocumentor 2 we wanted to reintroduce and expand upon that concept by offering to generate Reference Documentation. Inspiration has been drawn from Sphinx but the intention is to differ from that tool on specific points and to provide a pure PHP framework for generating reference documentation.

User stories

1. As a developer I want to use my input markup language of choice so that I do not have to learn a new markup language to write my documentation
2. As a user I want to have access to the documentation in the format that I desire so that I can ready it the way that suits my specific need
3. As a developer I want to generate multiple (types of) documents for each project so that I can create documents tailored to a specific user group
4. As a user I want to access the (pieces of) HTML generated documentation from the main menu of phpDocumentor so that I can easily access the docs
5. As a user I want to have a table of contents per document to navigate more easily
6. As a developer I want to link between documents so that I can refer to topics in other documents
7. As a developer I want to be able to insert customized content so that I can include contents that fall out of scope of this specification such as generated UML diagrams using PlantUML
8. As a developer I want to apply my own custom look and feel so that the reference documentation matches my house style or the style of the phpDocumentor template

Technical user stories

1. As a developer I want this functionality to be contained in a plugin so that I can enable it when desired
2. As a developer I want to be able to pass configuration options so that I can alter the behaviour of the plugin
3. As a user I want to generate reference documentation without API documentation so that I can use this tool for other languages as well.

Bonus stories

1. As a developer I want to continue using the old tutorial style of PHPDoc1 in my projects so that I do not have to convert my existing documentation.

Story 1: As a developer I want to use my input markup language of choice so that I do not have to learn a new markup language to write my documentation

Developers work best with the tools they know, and that includes writing documentation with the markup that suits your team best. As such we want phpDocumentor to be flexible with the number of input types that can be offered.

During this stage we will focus on the following input types:

• Markdown, this is the default language as it requires no installable dependencies; only the Markdown library provided by @michelf
• ReST, the Pandoc utility (a haskell tool) offers support for converting ReST
• Textile, the Pandoc utility (a haskell tool) offers support for converting Textile
• LateX, the Pandoc utility (a haskell tool) offers support for converting LateX
• DocBook, we want to be able to parse the DocBook format (using the PhD PHP extension) to provide compatibility with the original tutorials

All input types may only be applicable with specific output formats as not all tools are able to convert between eachother. Another option is to use Pandoc to convert from the HTML output of another conversion process to the intended output.

Example: suppose I want to convert from DocBook to latex, neither of the tools are capable of such a conversion but by combining PhD and pandoc you can do this by converting in between.

Story 2: As a user I want to have access to the documentation in the format that I desire so that I can ready it the way that suits my specific need

Story 3: As a developer I want to generate multiple (types of) documents for each project so that I can create documents tailored to a specific user group

Story 7: As a developer I want to be able to insert customized content so that I can include contents that fall out of scope of this specification such as generated UML diagrams using PlantUML

Consider using Twig to pre-render the documentation files?

It would be nice to be able to add commenting to the API and/or Reference docs; the best way to do this might be to implement Disqus support?

The following needs to be taken into account:

• Documentation must be able to be used offline but the comments may be disabled in that mode

Using the ignore option does nothing at all, no directory specified is ignored, and no error is thrown either. Is this functionality implemented?

C:\wamp\bin\php\php5.3.1>php.exe "C:\docblox\bin\docblox.php" project:run -d "C:\test" -t "C:\docbloxoutput2" --force -v --ignore "c:\test\test"

2011-04-19T13:32:14+00:00 INFO (6): [2.26mb]: Starting to process 2 files
2011-04-19T13:32:14+00:00 INFO (6): [2.26mb]: Starting to parse file: C:\test\test\newtest.php
2011-04-19T13:32:14+00:00 INFO (6): [2.81mb]: Starting to parse file: C:\test\test.php
*snip*
2011-04-19T13:32:14+00:00 INFO (6): [3.29mb]: Processing the file: \test\newtest.php as C:\docbloxoutput2\test_newtest.html
2011-04-19T13:32:14+00:00 INFO (6): [3.29mb]: Processing the file: \test.php as C:\docbloxoutput2\test.html

• A DocBlock tag of a structure contained in a class should translate the $this and self type to the name of the current class
• The templates should be adapted so that the $this keyword mentions that this is a Fluent Interface type (and thus only returns the same instance).
• Add a warning to DocBlox when the $this type is encountered in a static context

I don't know symfony in details, but with the latest version(downloaded through pear), they have the sfTimer.class.php under symfony/debug directory, hence your require_once in bin/docblox won't find that under 'symfony/sfTimer.class.php'
if you don't have some specific reason for this, then I would like to get that changed to
symfony/debug/sfTimer.class.php

Tyrael

Before the refactoring of the graph generation the SVG shows up as a small bounding box.
Now the item needs to be retested.

The PEAR dependency throws a lot of E_STRICT warnings. I recommend disabling them in bin/docblox.php by adding this near the top:

error_reporting(E_ALL & ~E_STRICT);

with the introduction of namespaces has the @Package tag become obsolete and it seems incomplete. Especially since it is adviced to omit the @Package tag when working with namespaces.

Hi.

In the output of Docblox, the full path to a file is used in the title of the HTML file, as well as the name of the HTML file. This means that if you have a long path, the filenames will be long, as well as the title, while adding little to no extra usable information. I'd suggest replacing the full path with a path relative to the directory that is parsed.

The README, TODO and/or INSTALL file need to be transformed from Markdown (other formats?) to HTML and given a place in the menu structure.

Hi.

While generating API documentation, I encountered the following error:

sphoof@web01:/www/sphoof/sphoof.nl/lib/Docblox$ ./bin/transform.php -t /www/sphoof/sphoof.nl/www/api-docs/ -s /www/sphoof/sphoof.nl/lib/Docblox/
Warning: DOMDocument::load(): Document is empty in /var/www/sphoof/sphoof.nl/lib/Docblox, line: 1 in /var/www/sphoof/sphoof.nl/lib/Docblox/DocBlox/Writer/Xslt.php on line 102

The error is my own fault (as I should have passed the filename itself, instead of only the path), but it wouldn't hurt to have a more descriptive error message.

When fileinfo support is added to PHP 5.2.x via pecl repositories, the constant FILEINFO_MIME_ENCODING is not available.

See the following from PHP documentation

FILEINFO_MIME_ENCODING  (integer)
Return the mime encoding of the file. Available since PHP 5.3.0. 

As minimum version is 5.2.9 iirc, this should be changed to be php 5.2.x compliant
I fixed the problem on my local side by checking the PHP version. Seems like in older versions, fileinfo cannot be used to check the encoding. This is, what I added:
version_compare(PHP_VERSION, '5.3.0') >= 0

I've noticed that Docblox has some dependencies to these projects, it should be documented somewhere.
now that we have pear package we could suggest to the users to do:
pear channel-discover pear.symfony-project.com
pear install symfony/symfony
pear channel-discover pear.zfcampus.org
pear install zfcampus/zf

Tyrael

I'm planning to use Docblox for replacing phpdocumentor in my jenkins build.
my problem is, that jenkins also uses a file config.xml, so I would either put the docblox config xml to another directory, or rename it and pass that with -c
it think it would be a good idea, to rename the default config.xml to for example docblox.xml, this way I could put that with my other configs (config.xml for jenkins, phpunit.xml.dist for phpunit) to the same directory

it would be a good thing, if we could have a batch script for windows, so it could be used just like the bin/docblox on linux.
if you need help, you can check the phpunit.bat for example, or maybe I could put together it for you also.

Tyrael

• Multiple @Package tags provide ambiguity and the system shows and empty package in the template; a CRIT log should be thrown when a DocBlock contains more than 1 @Package or @subpackage
• No @subpackage without @Package; an error should be thrown whenever a @subpackage is encountered without an @Package
• if an @param's type differs from the actual argument's typehint; when no typehint is present the @param may be of type scalar, null or resource. When the @param has multiple types the typehinting check is skipped.
• if a @param has multiple types, the argument has a typehint but there is no default found means an invalid situation has arised.

The example tag needs to be implemented as described here:
http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_tags.example.pkg.html

-Additionally the output needs to be parsed by GeSHi-
SyntaxHighlighter should be included with the template to do ad hoc Syntax Highlighting of the source

An option needs to be added to the XSL writer which modifies the behavior of the treeview to fully auto-expand on pageload

When you enter a search query and try to click on a result nothing happens when in Chrome; Firefox seems to do OK.
Testing can be done on: ci.docblox-project.org/job/DocBlox/API_Documentation/?

We've setup Jenkins to generate Docblox for us. The first step of creating the structure.xml file seems to work fine, but the XSLT parsing fails because stylesheets cannot be loaded.

The workspace looks something like this:

/var/lib/jenkins/Project Name With - Spaces/workspace/build/docblox <-- docblox project root, with bin/doctrine.php
/var/lib/jenkins/Project Name With - Spaces/workspace/target/phpdocs <-- output path
/var/lib/jenkins/Project Name With - Spaces/workspace/library <-- path being parsed

With this as the workspace, when running project:run we get errors like:

 [exec] Starting transformation of files (this could take a while depending upon the size of your project)
 [exec] PHP Warning:  XSLTProcessor::importStylesheet(): I/O warning : failed to load external entity "chrome.xsl" in /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Transformer/Writer/Xsl.php on line 51
 [exec] PHP Stack trace:
 [exec] PHP   1. {main}() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/bin/docblox.php:0
 [exec] PHP   2. DocBlox_Task_Project_Run->execute() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/bin/docblox.php:30
 [exec] PHP   3. DocBlox_Task_Project_Transform->execute() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Task/Project/Run.php:98
 [exec] PHP   4. DocBlox_Transformer->execute() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Task/Project/Transform.php:154
 [exec] PHP   5. DocBlox_Transformer_Transformation->execute() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Transformer.php:307
 [exec] PHP   6. DocBlox_Transformer_Writer_Xsl->transform() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Transformer/Transformation.php:212
 [exec] PHP   7. XSLTProcessor->importStylesheet() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Transformer/Writer/Xsl.php:51

 [exec] Warning: XSLTProcessor::importStylesheet(): I/O warning : failed to load external entity "chrome.xsl" in /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Transformer/Writer/Xsl.php on line 51

 [exec] Call Stack:
 [exec]     0.0003     634360   1. {main}() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/bin/docblox.php:0
 [exec]     0.0111    3071352   2. DocBlox_Task_Project_Run->execute() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/bin/docblox.php:30
 [exec]     0.1634    4741200   3. DocBlox_Task_Project_Transform->execute() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Task/Project/Run.php:98
 [exec]     0.1897    5236456   4. DocBlox_Transformer->execute() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Task/Project/Transform.php:154
 [exec]     0.2131    5288856   5. DocBlox_Transformer_Transformation->execute() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Transformer.php:307
 [exec]     0.2131    5288856   6. DocBlox_Transformer_Writer_Xsl->transform() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Transformer/Transformation.php:212
 [exec]     0.2133    5290352   7. XSLTProcessor->importStylesheet() /var/lib/jenkins/jobs/Flymuch Application - Generate Docs/workspace/build/docblox/src/DocBlox/Transformer/Writer/Xsl.php:51

The structure.xml and other meta files are generated Ok, but the HTML output is not.

if we move the workspace to:

/tmp/no_more_spaces

All is well.

When there is only one extension:

php

you get error:
Fatal error: Call to a member function toArray() on a non-object in DocBlox\Arguments.php on line 252

Call Stack:
0.0016 356112 1. {main}() bin\parse.php:0
0.0494 1237248 2. DocBlox_Arguments->getFiles() bin\parse.php:41
0.0494 1237248 3. DocBlox_Arguments->parseFiles() lib\DocBlox\Arguments.php:231
0.0512 1242968 4. DocBlox_Arguments->getExtensions() lib\DocBlox\Arguments.php:210

In version 0.8.3 an error ocurres if there isn't a structure.xml file in the /output/ dir that comes with DocBlox (i.e. if you use --target to tell parse.php put it elsewhere), because Abstract.php tries to set it as a source in it's constructor (line 28). To clarify, this occurs despite using --source pointing to the right file.

I'm guessing that either the class property needs to be set directly (circumventing the setter method) or, if it is essential that the setter is used, it needs to be set just before it is needed, instead of on class construction.

Currently the include section of a file's documentation does not click-through to a corresponding file. This should be added.

Hi.

When generation of the documentation is complete, the output looks excellent apart from two minor nuisances: first of all, I can see
tags where the code actually contains a line-end, so there seems to be one too many nl2br conversion.

Second, I write many classes in one file. This results in some odd floating issue: the description of properties on the right will float to the absolute right. The second box of properties however floats to the left side of the previous box. This is in Firefox and Opera, haven't tested other browsers.

If you try to parse the same directory, to the same output twice with the same parameters Docblox will throw a strange error after the second attempt (the first one succeeded)

Notice: iconv(): Detected an illegal character in input string in C:\docblox\src\DocBlox\Reflection\File.php on line 174

Notice: iconv(): Detected an illegal character in input string in C:\docblox\src\DocBlox\Reflection\File.php on line 174

Notice: iconv(): Detected an illegal character in input string in C:\docblox\src\DocBlox\Reflection\File.php on line 174

Every visible structure should receive icons on key locations (TBD) indicating their type (method, function, property, etc) and their visbility (public, protected, private).
Please mind that in the data/images/icons folder there are already icons for types; these should be used or replace with improvements.

Image_GraphViz relies on the PEAR System.php and other dependencies. This makes it hard to deploy DocBlox in an environment where no PEAR is present.
Since Image_GraphViz is antiquated and throws quite a bit of deprecated warnings and notices I believe it to be a good thing to replace it with another library which does not depend on externals other than Zend Framework.

it would be really useful for me (and I think I wouldn't be alove with this) if you could provide Docblox through pear.
you can use pirum for that, thats really easy
http://www.pirum-project.org/

thanks

Even when you put docblocks in front of them Docblox will ignore those. I'm not sure if this is just not yet implemented, or a setting somewhere.

Add DocBlock templates as implemented in phpDocumentor: http://manual.phpdoc.org/HTMLSmartyConverter/HandS/phpDocumentor/tutorial_phpDocumentor.howto.pkg.html#basics.docblocktemplate

With Docblox it is possible to mix and match multiple directories (-d) and files (f).
Now we take the folder of the first -d option to extract the 'base' folder; which is cut from the filenames.
This mechanism is to 'simple' and should be replaced with a mechanism which finds the highest folder that every file and directory have in common and use that as basis.

When parsing (and transforming) you get 'the log directory does not appear to be writable....' even if everything is OK and it should work.

The problem is that in DocBlox/Abstract.php on line 247 function check if FILE is writeable insted of FOLDER.

P.S. Runing that on windows machine

(there could be same problem on line 187 - same file debug() function)

We want to add markup to a Long Description; since people may have difference preferences in this we want to add a mime-type to a DocBlock which details which mark up is used. By default the markup is parsed as Markdown

On the launch of DocBlox for ZF we noticed that the main feedback is that the XSL templates are not clear enough.
In order to improve this we need to refactor the XSL templates to provide better readability.

When doing this we should also change the following:

• Split XSL files into smaller chunks to provide easier overridability
• Require basic theme XSLs to manually include all their components to prevent inclusion problems and allow the user to use, for example, a custom Chrome around the basics of the default.
• Split CSS files into more manageable chunks to allow easier overriding for users.
• Import all necessary CSS files in the theme.css
• Drop auto-inclusion of the default.css but import from theme.css

When using:

php bin/docblox.php project:run -d /path/to/src -t build/

you get the following error on the second "Transform" task:

--------8<-------
ERROR: Option "d" is not recognized.

Not yet implemented
--------8<-------

This is due to the "execute" method in DocBlox_Task_Project_Run which instantiates both the parse and transform tasks which parse the command line options. Option d is not a valid open for Transform.

We should research if and how connections between Docs may be possible; for example Aura Framework has multiple modules with each their own docs but with possible interoperability.