Newsgroups: php.doc,php.internals
Path: news.php.net
Xref: news.php.net php.doc:969375071 php.internals:27700
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Received-SPF: error (pb1.pair.com: domain php.net from 140.211.166.39 cause and error)
DomainKey-Status: good
DomainKey-Signature: q=dns; a=rsa-sha1; c=nofws;
	s=mx; d=php.net;
	h=From:Subject:To:Date;
	b=Z2azvl6FD/+lx6+j28bKi0pLTvSWejai6xQREZqic6JoyVQp4h5hpogMPPJHWl62
	sXBsYUT9aMKLakKgdhgUvJ2YbZ4oHqlkdDUIz4XTt1C3vGnd7drZB7ze9ZFVp8d3
Message-ID: <45BCE549.9000200@php.net>
Date: Sun, 28 Jan 2007 10:02:49 -0800
User-Agent: Thunderbird 1.5.0.9 (Windows/20061207)
MIME-Version: 1.0
To:  internals@lists.php.net,  didou@php.net,  phpdoc@lists.php.net
Content-Type: text/plain; charset=UTF-8; format=flowed
Content-Transfer-Encoding: 8bit
Subject: Inproving the Documentation
From: pollita@php.net (Sara Golemon)

> 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.

> 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?

> 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.

> This small @doc tag could _slightly_
> improve/optimize/sanitize our work on the
> documentation. By adding some SQL logging
> in loginfo.pl, and storing the following:
>
>  * date: commit date
>  * login: CVS account of the developer
>  * branch: CVS branch
>  * files: Changed files
>  * commit: Commit message before @doc
>  * desc : Optional developer description after @doc
>
>  We would be able to have an interface
> displaying a dynamic phpdoc TODO, with
> some nice features like a search by PHP
> version, extension, assignee, keywords..
>
Sounds sexy...

> Additionally, we can imagine adding an
> online help feature on the interface, by
> setting a �help� flag on some hardly
> understandable change, to have login@php.net
> notified of our need for enlightenment.
>

Well, this sounds like it's more suitable for a manual process, but
however you'd like...

-Sara