Re: Internal object orientation documentation available!

On Wed, Jun 12, 2013 at 10:04 PM, Nikita Popov <nikita.ppv@gmail.com> wrote: > On Wed, Jun 12, 2013 at 11:04 AM, Terry Ellison <ellison.terry@gmail.com > >wrote: > > > On 10/06/13 19:33, Nikita Popov wrote: > > > >> We just published some rather extensive documentation on internal object > >> orientation: > >> > >> > >> http://www.phpinternalsbook.**com/classes_objects.html< > http://www.phpinternalsbook.com/classes_objects.html> > >> > >> This is part of a larger project aimed at documenting the engine and > >> making > >> it accessible to new contributors. > >> > > This looks like an excellent beginning so thanks. A few general > comments: > > > > 1) I notice that your book is "© Copyright 2013, Julien Pauli - Anthony > > Ferrara - Nikita Popov. All Rights Reserved" rather than GDFL or one of > > the CC variants of open document licences. They only issue that I see > here > > is that I -- and possibly others -- might be a bit guarded in providing > > comment and input if that content was being transferred to the authors > > unconditionally. Also if you are reserving all rights then you will need > > to be careful to ensure that all the content is yours and not extracted > > from an open or other 3rd party source. Surely this going to add to your > > authoring burden? > > > > This is just a legal precaution, because we are not yet exactly sure about > the publishing formats for this project. If we wanted to actually have a > (printed) book, then questions of ownership can become problematic. Anyway, > I'm pretty sure that we will publish this under a CC license eventually. > > 2) Wikipedia, for example, contains a lot of good in-depth explanation of > > CompSci concepts and standard patterns such as > > http://en.wikipedia.org/wiki/**Hash_table< > http://en.wikipedia.org/wiki/Hash_table>. > > You might consider the content cut: when you include basic discussion of > > 101 principles (e.g. on HashTables); and when you limit > > your content to their PHP-specific implementation, with suitable > > references to the 101 stuff. Tending to the former will make the book a > lot > > longer, albeit standalone. Your call, but I would have thought that the > > majority of the readership by nature will have some CompSci background > and > > so want to skip the 101 stuff, or be referenced out to the appropriate > > in-depth WP or other reference. > > > > We don't have particularly much "101 stuff" to cover (basically just > hashtables), in which case I think its better to include a small > introduction to the topic to make things self-contained. Also, this project > is targeted not just at developers with years of C experience, but also at > people coming from a more higher-level (PHP) background, in which case > intimate knowledge of things like hashtables probably can't be expected. > > > > 3) What is your preferred markup format for feedback and contributions? > > E.g. do you maintain an ODF or Docbook XML under some accessible git > > repository, or is is a case of (for example) > > > > hashtables/basic_structure.html para at line 138. Not quite true that > > "the arBucket array will never shrink down: you can not reduce a PHP > > array, you only can grow it". You can always implement your own > > resizer by realloing the arBucket array and the calling > > zend_hash_rehash() to do this. (This would be a good standard hash > > API function by the way. > > > Heh, how did you get to that page? Wasn't supposed to be linked anywhere, > as that chapter isn't done yet. In any case, we are writing this in RST > (reStructured Text) in a private git repo (which will be made public > sometime down the road). So if you have feedback, no need to write text in > any particular format, just point us to what wrong / missing (or any other > suggestions) and we'll fix it. > > Regarding your particular example: Agree that this wasn't right in that > formulation. The text now says "while the arBuckets array automatically > grows, it will *not* shrink when you remove elements". I would rather not > mention the hack to implement the shrinking though, because its bad style > to directly mess with the members of the HT. > > Yes that was my writings. As I'm not English :-) I may miss words or sometimes turn sentences to a different meaning from what I initially thought in my native language. Nikita fixes that ;-) Julien.Pauli