Re: Announce: Gjs documentation almost ready!

[Giovanni Campagna <scampa giovanni gmail com>]

2014-03-05 16:51 GMT+01:00 Stefan Sauer <ensonic hora-obscura de>:
> On 03/04/2014 04:18 PM, Giovanni Campagna wrote:
> > 2014-02-27 16:53 GMT+01:00 Stefan Sauer <ensonic hora-obscura de>:
> > > 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