Re: Rudimentary documentation of gnome-shell JS files

["Jasper St. Pierre" <jstpierre mecheye net>]

On Fri, Sep 14, 2012 at 8:49 AM, Amy <mathematical coffee gmail com> wrote:
> Hi all,
>
> I've done a sort of "index" of the gnome-shell js files (in js/ui and
> js/misc) for GNOME 3.2 and 3.4, listing briefly what each file does
> and giving also a quick summary of classes in each file.
>
> I thought I'd share it on the list in case anyone wants a quick guide.
> I imagine this will mainly be new gnome-shell-extension developers
> saying "I want to write an extension that modifies the XYZ behaviour,
> what files should I look at?" - they can quickly locate some relevant
> files as a starting point and then go read those files. It is by no
> means definitive (or entirely correct !! I'm still learning myself -
> corrections welcome. 'specially all the DBus stuff which still
> confuses me greatly - "server", "proxy", "object", ...), but it may be
> of some use.

Are you familiar with the core concepts of DBus? That is: bus names,
objects, and interfaces? If not, I might write something up about that
soon.

If the shell provides a service (like the magnifier or notification
daemon), it exports an object on the bus, which implements the
specified interface. The term "DBus Server" isn't used to describe
that; "DBus Server" usually refers to the central thing that manages
the bus. It's usually a "DBus Service".

When trying to call a remote method on another object (like asking
upower to suspend us), there's a fake object that looks like it has
local methods ( so you can do upower.SuspendMePlease() ). That fake
object is called a "proxy".

> It lives here: http://mathematicalcoffee.blogspot.com.au/2012/09/gnome-shell-javascript-source.html

This is quite awesome! Thanks for this.

> However, is there some sort of gnome shell extensions wiki that I
> could upload this to so that it could be collaboratively worked on? I
> envision there being a quick index of file -> summary of what it does
> (e.g. "status/network.js - the network indicator") along with a wiki
> article for each file with more details. Or perhaps it might be
> worthwhile for me to try integrate some of these comments into the JS
> source in preparation for eventually running a documentation generator
> (some sort of doxygen equivalent for javascript) over it.
>
>
> Corrections & suggestions welcome (though if there's a wiki page I can
> put it on we can all correct/add to it in bits and pieces).

Creating a wiki page would be a first good step. We should eventually
add this to some form of in-tree generated documentation in some way,
but I don't know of a good JS documentation solution, and it's quite
hard to do generically (as I've spoken to you about before).

> cheers
> _______________________________________________
> gnome-shell-list mailing list
> gnome-shell-list gnome org
> https://mail.gnome.org/mailman/listinfo/gnome-shell-list



-- 
  Jasper