DocBlocks and Developer Documentation

[cmb]

Hello Community,

a while ago we have decided to adopt the PEAR coding standards as codings standards for the core of CMSimple_XH. According to the CS DocBlock comments should be used for every entity, what should already make the code better understandable (and could be useful for IDEs which automatically parse these DocBlocks and show them as calltips). These DocBlocks can automatically be processed by the PHPDocumentor [1], so every developer can create current documentation in his working copy. I suggest to keep the documentation in the WC, and to not commit it to SF.

Furthermore I suggest making available the generated documentation online, when XH 1.6 will be released. This should be helpful for plugin developers and template designers as a reference, particularly if we stick to the convention to mark internal entities as private and use the since tag to mark new entities. IMO we should add some tutorials, which could be integrated to the documentation automatically, and can easily link to and be linked from entities. I suggest keeping these tutorials on SF in the folder tutorials/, which can be excluded from the releases by the build script.

Actually I don't expect any noticeable slowdown of CMSimple_XH due to the massive amount of comments in the source files, but if that is an concern, we could extend the build script to remove all these DocBlocks.

Christoph

[manu]

does anybody have PHPDocumentator successfully running on XAMPP 1.8.1 [PHP: 5.4.7]?
Installation on localhost seems ok but generating doc from sample file only gets a bunch of error msgs. like:

Code: Select all

Strict Standards:  Declaration of HTMLSmartyConverter::Output() should be compatible with Converter::Output($title) in C:\xampp\htdocs\PhpDocumentor\phpDocumentor\Converters\HTML\Smarty\HTMLSmartyConverter.inc on line 1934



Grabbing README/INSTALL/CHANGELOG

done


Tutorial/Extended Documentation Parsing Stage

done


General Parsing Stage

done

Converting From Abstract Parsed Data

Processing Class Inheritance


Processing Root Trees


Processing leftover classes (classes that extend root classes not found in the same package)
done processing leftover classes

Processing Procedural Page Element Name Conflicts


Sorting page elements...done
Formatting @uses list...done

Creating Parent Directory http:
Creating Parent Directory http:\
Creating Parent Directory http:\\localhost
Creating Parent Directory http:\\localhost\PhpDocumentor
Creating Parent Directory http:\\localhost\PhpDocumentor\mysamples
Creating Directory http://localhost/PhpDocumentor/mysamples/docs
creating http://localhost/PhpDocumentor/mysamples/docs/\media
Creating Parent Directory http:
Creating Parent Directory http:\
Creating Parent Directory http:\\localhost
Creating Parent Directory http:\\localhost\PhpDocumentor
Creating Parent Directory http:\\localhost\PhpDocumentor\mysamples
Creating Parent Directory http:\\localhost\PhpDocumentor\mysamples\docs
Creating Parent Directory http:\\localhost\PhpDocumentor\mysamples\docs\
Creating Directory http://localhost/PhpDocumentor/mysamples/docs/\media
copying http://localhost/PhpDocumentor/mysamples/docs/\media/layout.css


Warning:  copy(http://localhost/PhpDocumentor/mysamples/docs/\media/layout.css): failed to open stream: HTTP wrapper does not support writeable connections in C:\xampp\htdocs\PhpDocumentor\phpDocumentor\Converter.inc on line 5387

copying http://localhost/PhpDocumentor/mysamples/docs/\media/print.css


Warning:  copy(http://localhost/PhpDocumentor/mysamples/docs/\media/print.css): failed to open stream: HTTP wrapper does not support writeable connections in C:\xampp\htdocs\PhpDocumentor\phpDocumentor\Converter.inc on line 5387

copying http://localhost/PhpDocumentor/mysamples/docs/\media/style.css


Warning:  copy(http://localhost/PhpDocumentor/mysamples/docs/\media/style.css): failed to open stream: HTTP wrapper does not support writeable connections in C:\xampp\htdocs\PhpDocumentor\phpDocumentor\Converter.inc on line 5387

ERROR: nothing parsed

any ideas?
regards manu

EDIT: ok, got it. For source and target absolute file paths are needed.

[cmb]

I'm using XAMPP 1.8.1. There's PHPDocumentor 1.4.4 already included, so no additional installation is necessary. If xampp\php is in the %PATH%, you can directly call phpdoc on the command line, and there relative directory paths do work fine. I've never tried the web interface.

[manu]

ahh, it's in the PEAR library, buried but still alive..
I installed the phpDocumentor again over the pear command line.
A few things are still strange but cmb has probably a clue:
doc parsing from the command line and from the web interface produce different output - strange.
All those strict standard warning in the parsed output doesn't make it look better.
Seems like phpDocumentor doesn't like php5.
Did anybody get it run properly on XAMPP 1.8.1? The included phpDocumentor version is 1.3 from 2003. The Problems are common.
Why not use phpDocumentor2?
regards manu

[cmb]

The included phpDocumentor version is 1.3 from 2003.

You're probably referring to phpdoc.bat, which is at version 1.3 from 2003. But the actual PHPDocumentor delivered with XAMPP 1.8.1 (no need to additionally install with PEAR) is 1.4.4 from 2011-12-03. You can see it in the generated documentation.

All those strict standard warning in the parsed output doesn't make it look better.
Seems like phpDocumentor doesn't like php5.
Did anybody get it run properly on XAMPP 1.8.1?

For me the command line interface works fine. My error_reporting is set to E_ALL & ~E_STRICT, so the strict warnings won't show up. For CMSimple developement that's no problem, as the debug mode overwrites this setting anyway.

Why not use phpDocumentor2?

IIRC I tried it months ago without success[1]. I'm not sure anymore what actually went wrong, but as PHPDocumentor 2 is ALPHA, it might not be the best solution, particularly as we don't need the recognition of PHP 5.3 features.

[1] Perhaps I'm mistaken, and I'm confusing this with PHPUnit, which I needed around the same time for the phputf8lib. Fortunately I found that this is also delivered with XAMPP 1.8.1.

[manu]

I didn't get the error_reporting set for line commands either with php.ini nor .htaccess. It seems pear just ignores it when run stand alone.
I deinstalled phpDocumentor and installed phpDocumentor2 with no issues.
As we leave the parsed output in the working copy this does no harm.
regards
manu

[cmb]

As we leave the parsed output in the working copy this does no harm.

On the contrary! As we have to switch to PHPDocumentor 2 sometime in the future, we can check for any potential incompatibilities, and if necessary switch to PHPDoc 2 sooner. One of these things could be the handling of @global tags for functions. At least for PHPDoc 1 one has to rely on the order of the global declaration, and cannot specify the name of the variable. See e.g. LinkCheck::check_links() in cmsimple/classes/LinkCheck.php. The way that it's documented now works fine. But the following, which I find more reasonable, gives strange results:

Code: Select all

    /**
     * Checks all links and returns the result view.     *
     *
     * @global array $c The page contents.
     * @global array $u The page URLs.
     * @global int $l The number of pages.
     * @return string  The (X)HTML.
     */ 

Is this the same with PHPDoc 2?

[manu]

PhpDocumentator doesn't register @global at all .
I try a go back to version 1.
Where did you set the error_reporting for the standalone pear? I didn't manage it with the root php.ini.

[cmb]

PhpDocumentator doesn't register @global at all .

Good to know! Of course the use of global variables isn't the best practise, but for CMSimple we can't get rid of them in the near future.

Where did you set the error_reporting for the standalone pear? I didn't manage it with the root php.ini.

This is quite likely taken from my "normal" php.ini (in xampp\php\). To be sure you might insert a phpinfo();exit(); at the beginning of phpdoc.inc (in my case it's in xampp\php\pear\PhpDocumentor\phpDocumentor\). This should display the php.ini in use.

[cmb]

I'm coming back to this topic because switching to PHP 5.3 seems to demand it. We already had some related discussion in http://cmsimpleforum.com/viewtopic.php? ... 365#p45365 in the meantime.

Anyhow, I'm in the progress to make Advancedform_XH 2.0, and I deemed it reasonable to make use of namespaces, so I lifted the requirements to PHP 5.3. Besides the already mentioned problems regarding unrecognized PHP 5.3 syntax, PhpDocumentor 1 fails completely if there are any anonymous functions in the code base. Apparently, there is no way to use the full PHP 5.3 feature set in combination with PhpDocumentor 1, so upgrading to phpDocumentor 2 appears to be appropriate.

However, phpDocumentor 2 still doesn't recognize @global tags, does not work with our other requirements, and I was not able to make it available for Phing's phpdoc2 task (I tried global Composer installation, PEAR and Phar without success).

Any ideas?

Shall we port CMSimple_XH to Java or .NET?