2014-03-05 16:51 GMT+01:00 Stefan Sauer <[email protected]>: > On 03/04/2014 04:18 PM, Giovanni Campagna wrote: >> 2014-02-27 16:53 GMT+01:00 Stefan Sauer <[email protected]>: >>> On 02/26/2014 08:27 PM, Giovanni Campagna wrote: >>> >>> Hello desktop developers, >>> >>> as some of you may have noticed, there has been some activity on the >>> documentation generator for gobject-introspection, and in particular a >>> lot of improvements on the Gjs side. >>> Now the result are beginning to appear, and you can see them here: >>> https://people.gnome.org/~gcampagna/docs/ >>> >>> In particular, what is interesting is that we blend in generated and >>> manually edited documentation. This allows us to remove all of GLib >>> and GObject that is not interesting or badly annotated, and it lets us >>> add things like GObject.Class ( >>> https://people.gnome.org/~gcampagna/docs/GObject-2.0/GObject.Class.html >>> ), which is the gjs specific way to define new GTypes. >>> I hope to finish with the other overrides soon (the biggest ones are >>> GLib.Variant and Gio.DBus*, but there's some minor stuff), which >>> should solve one of the greatest hurdles in taking up gjs programming. >>> The sources for this generation are not hosted anywhere, because I >>> don't know if it makes sense to store generated (or semi-generated) >>> files in git. I think it does, at least for GLib and GObject, because >>> the update is always manual. cairo has the same problem, because we >>> bind it manually, and the "native" gjs modules need documentation too. >>> >>> Of course, this location is only temporary, and I hope we will move to >>> library-web at some point. This would also fix the styling, which >>> right now is "poor" (it's a pure yelp-build of the mallard docs). >>> The interesting part, though, is that the documentation, at least for >>> the schematic parts, is correct and existing. >>> >>> >>> awesome! A few comments/questions: >>> >>> 1) are there plans to get this into devhelp? We need to figure a namespace >>> scheme for binding docs. The devhelp app itself already understands >>> different languages. All we need is a index file like the ones gtk-doc >>> generates. >> No, there are no plans to get this in devhelp. The HTML output is >> really just a way to get them somewhere in the internet without >> blocking on library-web, but the real deliverable is mallard, and >> devhelp does not understand that (while library-web does) >> >>> 2) I think it would be nice to share the css with gtk-doc so that the >>> various docs are closer to each other. >>> >>> 3) there seem to be empty Returns: tags in the docs - e.g. >>> https://people.gnome.org/~gcampagna/docs/Gst-1.0/Gst.Pipeline.get_bus.html >> Fixed now. > now this one has a weird ret-doc: > https://people.gnome.org/~gcampagna/docs/Gst-1.0/Gst.Pipeline.set_clock.html > instead of "Returns:" it says "ok".
Ugh, that "ok" is meant to be when multiple return values exist, so in C you have /** * my_object_get_foo: * @object: a #MyObject * @foo: (out): location for a #Foo * * Returns: %TRUE if @foo could be fetched successfully, %FALSE otherwise */ gboolean my_object_get_foo (MyObject *object, Foo ** foo); that in GJS becomes object.get_foo() : [ok: Boolean, foo: Foo] @ok: true if @foo could be fetched successfully, false otherwise @foo: location for a Foo So, having "ok" there sometimes is expected, but obviously there is a bug somewhere. I'll investigate. Anyway, if you find a bug in the gjs documentation, after checking it exists from the git repo (the people.gnome.org page is not always updated), please report it to gjs or glib/introspection (in the latter case, add me on Cc) Thanks! Giovanni _______________________________________________ desktop-devel-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/desktop-devel-list
