Newsgroups: php.internals
Path: news.php.net
Xref: news.php.net php.internals:30037
Return-Path: <philip@roshambo.org>
Mailing-List: contact internals-help@lists.php.net; run by ezmlm
Delivered-To: mailing list internals@lists.php.net
Received: (qmail 22312 invoked by uid 1010); 2 Jun 2007 04:31:30 -0000
Delivered-To: ezmlm-scan-internals@lists.php.net
Delivered-To: ezmlm-internals@lists.php.net
Received: (qmail 22290 invoked from network); 2 Jun 2007 04:31:29 -0000
Received: from unknown (HELO lists.php.net) (127.0.0.1)
  by localhost with SMTP; 2 Jun 2007 04:31:29 -0000
Authentication-Results: pb1.pair.com smtp.mail=philip@roshambo.org; spf=permerror; sender-id=unknown
Authentication-Results: pb1.pair.com header.from=philip@roshambo.org; sender-id=unknown
Received-SPF: error (pb1.pair.com: domain roshambo.org from 207.210.105.50 cause and error)
X-PHP-List-Original-Sender: philip@roshambo.org
X-Host-Fingerprint: 207.210.105.50 analucia.asmallorange.com  
Received: from [207.210.105.50] ([207.210.105.50:59471] helo=analucia.asmallorange.com)
	by pb1.pair.com (ecelerity 2.1.1.9-wez r(12769M)) with ESMTP
	id 24/40-17559-E92F0664 for <internals@lists.php.net>; Sat, 02 Jun 2007 00:31:28 -0400
Received: from c-24-20-30-252.hsd1.wa.comcast.net ([24.20.30.252]:53419 helo=[192.168.3.104])
	by analucia.asmallorange.com with esmtpa (Exim 4.63)
	(envelope-from <philip@roshambo.org>)
	id 1HuLGo-00088g-V3; Sat, 02 Jun 2007 00:31:19 -0400
In-Reply-To: <A1C3ADF2-0D60-4746-ACDF-6A1BDFCB1A81@wanderingknights.org>
References: <97180F0D-CB4C-4071-A859-38059C0DD1FF@wanderingknights.org> <Pine.LNX.4.62.0704252131190.1454@localhost> <0DFF3A59-3419-4A25-B907-E0E71FD41360@wanderingknights.org> <462FD093.90402@zend.com> <C74FB334-3BAF-4324-A439-235723F2EB3A@wanderingknights.org> <462FDB7B.8000907@zend.com> <8F6E78F4-9B53-43FA-8E7E-3460800F9AAD@wanderingknights.org> <4850AC0C-7268-4CE2-A192-771F459A2CB5@roshambo.org> <A1C3ADF2-0D60-4746-ACDF-6A1BDFCB1A81@wanderingknights.org>
Mime-Version: 1.0 (Apple Message framework v752.3)
Content-Type: text/plain; charset=US-ASCII; delsp=yes; format=flowed
Message-ID: <6DD3AF62-A773-4015-ACBE-B5178C4B2F03@roshambo.org>
Cc: internals@lists.php.net
Content-Transfer-Encoding: 7bit
Date: Fri, 1 Jun 2007 21:31:04 -0700
To: Gwynne Raskind <gwynne@wanderingknights.org>
X-Mailer: Apple Mail (2.752.3)
X-Antivirus-Scanner: Clean mail though you should still use an Antivirus
X-AntiAbuse: This header was added to track abuse, please include it with any abuse report
X-AntiAbuse: Primary Hostname - analucia.asmallorange.com
X-AntiAbuse: Original Domain - lists.php.net
X-AntiAbuse: Originator/Caller UID/GID - [47 12] / [47 12]
X-AntiAbuse: Sender Address Domain - roshambo.org
X-Source: 
X-Source-Args: 
X-Source-Dir: 
Subject: Re: [PHP-DEV] Documenting the Zend2 extension API
From: philip@roshambo.org (Philip Olson)

>
> <part id="internals2">
>   <title>&Internals2;</title>
>   &internals2.intro;
>   &internals2.buildsys.index;   <!-- configure options, ext_skel,  
> config.m4, config.w32, static vs dynamic builds -->
>   &internals2.structure.index;  <!-- ext_skel, module structure,  
> globals, lifecycle, tests -->
>   &internals2.memory.index;     <!-- management, persistence, TSRM -->
>   &internals2.variables.index;  <!-- zval, hashtable, references,  
> constants -->
>   &internals2.functions.index;  <!-- defining, arguments, return  
> values, passthru, aliasing -->
>   &internals2.objects.index;    <!-- classes, inheritance,  
> properties, methods, method-function mapping -->
>   &internals2.resources.index;  <!-- defining, creating,  
> retrieving, destroying -->
>   &internals2.ini.index;        <!-- defining, retrieving, changing  
> -->
>   &internals2.streams.index;    <!-- using, wrappers, contexts,  
> filters -->
>   <!-- grab the PDO section from &Internals; here? -->
>   &internals2.apiref.index;     <!-- full index of all APIs,  
> constants, macros, etc. -->
>   &internals2.ze1.index;        <!-- quick list of major  
> differences, short discussion re: OOP -->
>   &internals2.ze3.index;        <!-- quick discussion of major  
> changes, some details on Unicode -->
> </part>
>
> My thinking is to document ZE2 completely, since the differences  
> between 1 and 2 are small enough for the existing internals section  
> to be of use to anyone writing for 1, and 3 can be more fully  
> documented later (something I'm willing to take on as well).
>
> If I'm given a thumbs-down on this way of doing things, I'll take  
> the material I've written already and use it to update the existing  
> internals section, but I think this method has the best chance of  
> giving people the truly comprehensive online reference we've lacked  
> for extension writing up to this point.

Hello Gwynne,

Sounds good. Many times silence on this list means "Sounds good" and  
internals isn't too keen on defining a structure for  
documentation... :) So, go for it! Always feel free to ask questions  
while documenting this and as it all progresses let's be sure  
internals reviews the information too. Once the information is in  
manageable and smaller pieces you'll likely have more success getting  
feedback. And don't be a stranger on #php.pecl @ efnet (IRC) either.

Regards,
Philip