Torben, This is good stuff. I have the following suggestions:
1. I would add links to the basic.xml page in the paragraph where you state "A class may contain its own variables, constants, and functions." I'd link to the sections on properties, constants and methods. 2. I would also add in parenthesis after you describe variables and functions the words property and method, to make clear that classes have properties and methods, not variables and functions (even though the syntax is the same). These, of course, are style suggestions, and not problems with your documentation. I think the work you've done is great, and +1 from me on committing the changes. Best, Brandon On Mon, Sep 7, 2009 at 2:30 PM, Lars Torben Wilson <larstor...@gmail.com>wrote: > Brandon Savage wrote: > >> On Sep 7, 2009, at 3:47 AM, Lars Torben Wilson wrote: >> >> Hi all, >>> >>> While going through some bug reports I realized that the 'The Basics' >>> section of the PHP 5 classes and objects section, as it stands, could use >>> some attention. I've been going over it and and have rewritten much of it to >>> be more precise, and have also separated the class variables sect2 out into >>> its own sect1 and given it a bit of a rewrite as well. >>> >>> In days of old I would have just committed this and been done with it, >>> but since I've only recently been getting back into the documentation after >>> having been away for a few years, I wanted to see if there are any >>> objections to such an endeavour. :) >>> >>> For the most part the changes are to make the basics section a little >>> more reference-like and to provide a bit more specificity. I realize that >>> there is still work to be done, but this is, to me, a good first step toward >>> providing a true reference on PHP 5 class/object behaviour. >>> >>> I do realize that there is now some redundant content between the new >>> 'Class variables' sections and the existing 'Visibility' section, but this >>> can either be A) fixed, or B) thought of as a Good Thing since it merely >>> reinforces some important information. >>> >>> The new changes are available at the following URL if anybody cares to >>> take a look and comment on the idea: >>> >>> http://www.thebuttlesschaps.com/phpdoc/language.oop5.html >>> >>> Comments, criticisms, and feedback greatly appreciated! >>> >>> >>> Regards, >>> >>> Torben >>> >> >> Torben, >> >> To me this sounds like a great idea. Would it be possible for you to post >> up the diffs? I just want to see what changed, and I'm not very good at >> reading line for line. ;-) >> >> I can take them as a zip file if you like. >> >> Thanks! >> >> Brandon >> > > But of course! Where are my manners? ;) > > I've attached a tarball containing the diffs to language/oop5/basic.xml and > language/oop5.xml and the new language/oop5/variables.xml. > > > Torben >
