Re: Rudimentary documentation of gnome-shell JS files

[Yaa101 <yaa101 xs4all nl>]

-- 
(o_
//\  Regards, Groeten,
V_/_ Bas Burger.


On Fri, 14 Sep 2012 22:28:24 -0400
"Jasper St. Pierre" <jstpierre mecheye net> wrote:

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

  I agree, Extensive work! Also nicely presented.
> 
> > 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).
> 
  I suggest you add the files of /usr/share/gjs-1.0 to this story, they
  are more low level, but important to be known. :-)


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

  Try to find/make something that is flexible in how it presents the API
  And make it perform live, that if you change the arguments of a
  function/method, that the documentation changes along for the
  snapshot of that version number. Store the changes between version
  numbers like in SVN or GIT, maybe you are even able to couple the
  documentation generator to some versioning system.

  

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