php-gtk:gtkphd

Migration to Main Manual

The PHP-GTK manual will be integrated into the main PHP manual as an extension.

Progress

Stage One
  1. Create branches to phpdoc/doc-base and phpdoc/en
  2. Patch docgen.php script for PHP-GTK-specific Reflection idiosyncrasies.
  3. Create new docgen template set for PHP-GTK. In Progress
    • gtk/book.tpl
    • gtk/chapter.tpl (GTK+ sub-extensions)
    • gtk/class.tpl
      • fields (aka GObject properties)
      • signals
    • gtk/configure.tpl
    • gtk/constants.tpl
    • gtk/method.tpl
    • gtk/part.tpl (sub-extension parts)
    • gtk/reference.tpl
    • gtk/signal.tpl
  4. Finalize book format
Stage Two
  1. Copy as much well-formed documentation as possible from the old manual, without muddying the new format.
  2. Fill in any glaringly-missing documentation
  3. Merge branch into phpdoc/en/trunk/

Branches

phpdoc/doc-base/branches/gtk-docgen/: A fork of the docgen scripts to accommodate PHP-GTK's Reflection idiosyncrasies.

phpdoc/en/branches/php-gtk/: Branching the main manual so that our work on the PHP-GTK book doesn't interfere with “normal operations.”

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 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

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.txt · Last modified: 2017/09/22 13:28 by 127.0.0.1