php-gtk:gtkphd

Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revisionPrevious revision
Next revision		Previous revision
php-gtk:gtkphd [2010/01/08 21:11] – external edit 127.0.0.1php-gtk:gtkphd [2017/09/22 13:28] (current) – external edit 127.0.0.1
Line 1: Line 1:
-==== PHP-GTK PhD migration ==== +==== Migration to Main Manual ==== 
-PHP-GTK's docs should be moved to the [[doc:phd|PhD]] rendering system, but it is a fairly large job.+The PHP-GTK manual will be integrated into the main PHP manual as an extension.
  
-Would involve +=== Progress ===
-  - migrating the current documentation to a docbook 5 format +
-  - writing a PhD compatible theme to generate documentation +
-  - writing a reflection based updater to keep docs up to date with code (parsing signals, methods, properties and updating the xml) +
-  - getting autogeneration set up so PHP-GTK docs are generated on a regular basis+
  
-==== Progress ==== +== Stage One == 
-  - Working on a fork of docgen.php to pick up classes, methods and signals +  - <del>Create branches to phpdoc/doc-base and phpdoc/en</del> 
-  - Got appropriate markup for the signals stuff +  - <del>Patch docgen.php script for PHP-GTK-specific Reflection idiosyncrasies.</del> 
-  - Still need a theme, and no doubt other stuff+  - Create new docgen template set for PHP-GTK. __In Progress__ 
 +    * gtk/book.tpl 
 +    * gtk/chapter.tpl (GTK+ sub-extensions) 
 +    * gtk/class.tpl 
 +      * <del>fields (aka GObject properties)</del> 
 +      * signals 
 +    * gtk/configure.tpl 
 +    * gtk/constants.tpl 
 +    * gtk/method.tpl 
 +    * gtk/part.tpl (sub-extension parts) 
 +    * gtk/reference.tpl 
 +    * gtk/signal.tpl 
 +  - Finalize book format
  
 +== Stage Two ==
 +  - Copy as much well-formed documentation as possible from the [[http://gtk.php.net/manual/en/|old manual]], without muddying the new format.
 +  - Fill in any glaringly-missing documentation
 +  - Merge branch into phpdoc/en/trunk/
 +
 +=== Branches ===
 +[[http://svn.php.net/viewvc/phpdoc/doc-base/branches/gtk-docgen/|phpdoc/doc-base/branches/gtk-docgen/]]: A fork of the docgen scripts to accommodate PHP-GTK's Reflection idiosyncrasies.
 +
 +[[http://svn.php.net/viewvc/phpdoc/en/branches/php-gtk/|phpdoc/en/branches/php-gtk/]]: Branching the main manual so that our work on the PHP-GTK book doesn't interfere with "normal operations."
 +
 +[[http://svn.php.net/viewvc/phpdoc/modules/doc-gtk/|phpdoc/modules/doc-gtk/]]: Module for checking out PHP-GTK externals into a single working copy.
 +
 +=== Reflection Idiosyncrasies ===
 +PHP-GTK does not currently have proper Reflection data, beyond regular class->method, and such, linking. This means that the docgen.php script, which relies heavily on Reflection information, does not function properly without modification.
 +
 +The current solution to this issue is to utilize the .defs files present in the PHP-GTK extension sources, which themselves establish which classes exist in the extension. This is done by simply reading in all of the .defs files, then regex'ing them for of-object specifications, then running array_unique on the resulting set of class names. This produces a list of all defined classes in PHP-GTK.
 +
 +=== PHP-GTK-specific Constructs ===
 +PHP-GTK utilizes some constructs that are not present in other extensions; or, at least, are not standard. These need to be marked up specially for PHP-GTK.
 +
 +== Fields ==
 +Each widget class in PHP-GTK has a set of associated properties which are separate from both its member properties and inherited properties. These "GObject properties" are enumerated using GObject::list_properties(int gtype), where gtype is ClassName::gtype.
 +
 +== Signals ==
 +Each widget class in PHP-GTK has a set of signals, which are essentially callback names for certain actions. One example is the GtkButton "clicked" signal, which is emitted when a user clicks on that GtkButton widget.
 +
 +These signals can simply be marked up as a variant of the method format, as they are primarily callbacks. There are a [[http://gtk.php.net/manual/en/gobject.method.signal_query.php|few bits of information]] that are important to be clearly documented for each signal:
 +  * ID
 +     Each signal has a signal ID associated with it.
 +  * Name
 +     Each signal has a name.
 +  * Emitting Classes
 +     The list of classes which emit that signal
 +  * [[http://gtk.php.net/manual/en/gobject.enum.gsignalflags.php|GSignalFlags]]
 +     The signal flags are used to specify a signal's behaviour, the overall signal description outlines how the stages of a signal emission occur.
 +  * Return Type
 +  * Parameters
 +     Each signal handler callback accepts certain parameters, which are passed in when called. This is usually at the very least the object which emitted the signal.
 +
 +=== Book Structure ===
 +  * PHP-GTK (Book)
 +    * GTK+ (Part)
 +      * ATK (Chapter)
 +      * GDK (Chapter)
 +      * GTK (Chapter)
 +      * Pango (Chapter)
 +    * Extra (Part)
 +    * [...] (Part)
php-gtk/gtkphd.1262985105.txt.gz · Last modified: 2017/09/22 13:28 (external edit)

Page Tools