Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:64689
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain lsces.co.uk from 213.123.26.185 cause and error)
Message-ID: <50EC2BB4.7000503@lsces.co.uk>
Date: Tue, 08 Jan 2013 14:22:44 +0000
User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:17.0) Gecko/17.0 Firefox/17.0 SeaMonkey/2.14
MIME-Version: 1.0
To: "internals@lists.php.net" <internals@lists.php.net>
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 7bit
Subject: 'Documentation'
From: lester@lsces.co.uk (Lester Caine)

Having been using 'docblock' elements to document classes in PHP for many years, 
their use by PHPEclipse and PDE to provide type-hinting and via phpdocumentor to 
build developer documentation for classes, I simply haven't seen any need for 
some of the more recent developments.

Reflection/Annotations are just another way of 'documenting' classes - aren't 
they? It's not a level of complexity that I have seen a need for, in the same 
way that 'Accessors' just seem to be further complexity without a real need for 
many users.

By using established practices and developing them as extensions that can be 
disabled if not required, then we can all work with the level of complexity that 
we are comfortable with? 'docblock' comments make the code readable, and can be 
stripped in much the same way as javascript is 'packed' for running code, but 
using the same standard as the basis for other extensions information that can 
be parsed/compiled as required does have some sort of logic? The information 
required is on the whole the same for the IDE and documentation and currently a 
large swath of code already has all of the core comments already? Surely the 
starting point is to ensure that the basic docblock standards work with all of 
the 'new' features, and then everything else builds on top of that?

-- 
Lester Caine - G8HFL
-----------------------------
Contact - http://lsces.co.uk/wiki/?page=contact
L.S.Caine Electronic Services - http://lsces.co.uk
EnquirySolve - http://enquirysolve.com/
Model Engineers Digital Workshop - http://medw.co.uk
Rainbow Digital Media - http://rainbowdigitalmedia.co.uk