halting problem :: Documentation

Davyd, the GTK+ Perl bindings come with documentation in the perldoc format (which works upon man); each object has its unique perldoc page, so if you need to know all the methods of the Gtk2::TreeView widget, all you have to do is open a terminal and type:

$ perldoc Gtk2::TreeView

And you’ll be greeted by a screenful like this:

TREEVIEW(1)         User Contributed Perl Documentation        TREEVIEW(1)

NAME
       Gtk2::TreeView

HIERARCHY
         Glib::Object
         +----Glib::InitiallyUnowned
              +----Gtk2::Object
                   +----Gtk2::Widget
                        +----Gtk2::Container
                             +----Gtk2::TreeView

INTERFACES
         Glib::Object::_Unregistered::AtkImplementorIface

METHODS
       widget = Gtk2::TreeView->new ($model=undef)

           * $model (Gtk2::TreeModel)
...

Support of man pages, by the way, is sorely missed inside GTK+ itself: instead, you’ll have to use devhelp or point your browser to a long URI; I love devhelp, but I’m usually coding (with) development releases of many libraries, all installed inside a jhbuild sandbox so in order to make it find the autogenerated API documentation you’ll have to build devhelp inside the sandbox too - which is unnecessary pain I’d like to avoid inflicting upon myself.

Anyway, perldoc to the rescue: at the end of the object page you’ll find the SIGNALS section - if the object’s class exports signals, that is - which looks like this:

SIGNALS
       set-scroll-adjustments (Gtk2::TreeView, Gtk2::Adjustment, Gtk2::Adjustment)
       row-activated (Gtk2::TreeView, Gtk2::TreePath, Gtk2::TreeViewColumn)
       boolean = test-expand-row (Gtk2::TreeView, Gtk2::TreeIter, Gtk2::TreePath)
       boolean = test-collapse-row (Gtk2::TreeView, Gtk2::TreeIter, Gtk2::TreePath)
       row-expanded (Gtk2::TreeView, Gtk2::TreeIter, Gtk2::TreePath)
       row-collapsed (Gtk2::TreeView, Gtk2::TreeIter, Gtk2::TreePath)
...

As you can see, you have the signal name, the arguments of the callback and the eventual return value. The “gotcha” is that there are no named arguments, so you’ll have to know the C counterpart of the signal; this might be a worthy addition to the API documentation generation module.

Another dirty trick is to use the Data::Dumper module inside a callback you don’t know which arguments passes:

sub my_unknown_callback {
    use Data::Dumper;

    print STDERR Dumper(@_);
}

Which will print whatever the callback gives you - even descending into hashes and arrays if it knows how to print their contents.

If you don’t want to use a terminal and the perldoc command, there’s the Gtk2::Ex::PodViewer widget on CPAN, which comes with a podviewer application which you can use to browse the entire Perl documentation available on the system,or you can download PodBrowser which does a bazillion things more.