Re: Documentation for gnome-shell

[Sander Dijkhuis <sander dijkhuis gmail com>]

On Wed, Aug 5, 2009 at 4:06 PM, Joseph Scheuhammer<clown utoronto ca> wrote:
> [...]
> I have a couple of documentation questions.  First, is there any
> architecture documents that describe how the various objects interact?  Like
> an overview of how these object fit together?

Not really as far as I know. The Development wiki page [1] comes closest.

But here are some descriptions of JavaScript files that might not have
an obvious function.
 - appDisplay: handles all application display stuff in the Activities overview
 - genericDisplay: the framework used by appDisplay and docDisplay
 - button: used for the two buttons in the top panel
 - dash: defines the non-workspace part of the Activities overview
 - dnd: implements drag-and-drop
 - link: used for the pagination buttons below search results
 - lookingGlass: the debugger that you open by Alt-F2 'lg'
 - overlay: the Activities overview
 - tweener: an animation framework
 - widget(Box): used in the sidebar

> Secondly, there are a set of "gi" objects that are typically imported and
> used by the JavaScript objects.  They look to me like C/C++ Glib (?) objects
> that have JavaScript bindings.  An example is "imports.gi.Big".  Is there
> any documentation of these objects'/classes' API?  Using "Big" as an
> example:  What isa Big?  What are its methods?

I think 'gi' stands for GObject Introspection [2]. These 'gi' objects
are mostly introspected Glib-based libraries written in C. For
understanding these, you can use both their API references [3] and the
description files in ~/gnome-shell/install/share/gir-1.0.

Exceptions are Big, Tidy and Shell which are provided by gnome-shell
itself. The first two provide help with Clutter layout and Shell
provides gnome-shell-specific functions. I don't think they have
online documentation, but you can read their source code and .gir
files in ~/gnome-shell/source/gnome-shell/src.

> Actually, it would be useful if there are API documentation for the
> JS-objects themselves (e.g., Overlay).

I started working on that some months ago in Bug 574573 [4], but those
docs are outdated and the system still needs some work.


[1] http://live.gnome.org/GnomeShell/Development
[2] http://live.gnome.org/GObjectIntrospection
[3] http://library.gnome.org/devel/references
[4] http://bugzilla.gnome.org/show_bug.cgi?id=574573