Everything
php
Learn Community Releases The PHP Project
Home » Project » Newsgroups » php.internals » Inproving the Documentation »

Inproving the Documentation

php.internals

Sara Golemon

19 years ago
> 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

Philip Olson

19 years ago
>> 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