Newsgroups: php.doc,php.internals
Path: news.php.net
Xref: news.php.net php.doc:969375084 php.internals:27702
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain roshambo.org from 207.210.105.50 cause and error)
In-Reply-To: <45BCE549.9000200@php.net>
References: <45BCE549.9000200@php.net>
Mime-Version: 1.0 (Apple Message framework v752.3)
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed
Message-ID: <44D8B3B3-CFD3-4173-8A0A-BAFFAC9A5D7C@roshambo.org>
Cc: internals@lists.php.net,
 didou@php.net,
 phpdoc@lists.php.net
Content-Transfer-Encoding: 7bit
Date: Mon, 29 Jan 2007 00:43:39 -0800
To: Sara Golemon <pollita@php.net>
Subject: Re: [PHP-DOC] Improving the Documentation
From: philip@roshambo.org (Philip Olson)


>> Personally, I try to follow commits on
>> php.cvs, bug reports, Change Log,
>> user notes on the online manual..
>> but I still have the feeling of missing
>> a lot of changes. After a year away from
>> the project, I have _no_ clue what was
>> added, when, and whether it was added
>> to our documentation or not.

> With regard to new features, I've kept the NEWS file up to date (as  
> have
> most other developers) with these changes and although these  
> entries may
> not be enough for a 3rd party to decipher into manual entries, I can
> certainly write up the ones with my name by them when the time comes
> (see note about PHP6).
>
> But that's just a question of features, there's also the "unicode
> semantics quirks".  Some functions which act in a perhaps-unexpected
> manner when used in unicode-semantics mode.  These are going to be  
> more
> difficult to track down, but I'll make an effort to catalog and  
> document
> the parts I worked on.

Many months ago this unicode topic was discussed a bit, and the  
following
RFC came into being (and was accepted):

     Proposal for documenting Unicode support:
     http://doc.php.net/php/rfc/rfc-proposal-show.php?id=6

Mehdi has rejuvenated the "update to the new doc style" effort,  
something
that has held the unicode (and recent PHP features in general)
documentation back a bit. That and the scary task of understanding the
unicode stuff, writing words to explain it, and doing so in a way that
confuses few. Choose a guinea pig extension and let's all make it  
happen.
And to those wondering at home, the PHP documentation source is in the
middle of a large change. Each function includes clearly defined  
structure
now... like roles/sections for unicode information, a ChangeLog, and
plenty more.

>> I know that you developers are willing
>> to help a lot with it, but that you cannot
>> manage to save the spare time needed to
>> do it the right way.
>>
> I admit that my additions, personally, in the past year have been left
> off the documentation radar, but that's due (mostly) to the fact that
> these additions have been to PHP6 and (as with PHP5) the lead time on
> any release is too long to start advertising features in the manual  
> that
> don't exist (from the perspective of the end user).  Where is the
> documentation team at with regards to when they feel PHP6 features
> should start appearing in the manual?

The policy is to document as soon as possible, so feel free to  
commit! :)
The manual does document some PHP 6 functions and features currently,  
but
not many. About every one or two months, a bug report is sent in by
a confused user ("...PHP 6 isn't released yet!") but the "About" section
mentions we document future PHP versions (yesterday it was updated to
reflect PHP 6). And, each function has a ChangeLog now. Granted using
present tense to describe PHP 6 can be confusing... it's just the way it
is. It'll be here soon!

     PHP versions documented in this manual:
     http://php.net/manual/about.phpversions.php

>> That's why I would
>> like to propose a simple/small/timeless
>> change in your CVS commit messages: If
>> you feel that the change need to be
>> documented, place the @doc keyword at the
>> end of your message log entry.
>>
> I like that idea.  It's a nice clear, consistent flag saying "look
> here!".  I'll use this from now on.

Cool, this should prove useful.

Regards,
Philip