Re: Announce: Gjs documentation almost ready!

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:

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 (
), 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
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.
Fixed now.
now this one has a weird ret-doc:
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 page is not always
updated), please report it to gjs or glib/introspection (in the latter
case, add me on Cc)



[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]