Re: Announce: Gjs documentation almost ready!

On Tue, Mar 4, 2014 at 10:18 AM, Giovanni Campagna <scampa giovanni gmail com> 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
> 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.

Fixed now.

> 4) having these " // Gjs wrapper for gst_pipeline_get_bus()" comment in the
> method synopsis looks weird.

That comment was Jasper's idea, my idea was "[native code for ...]"
(similar to what JS uses for native code functions already).
The comment syntax has the advantage of being valid JS - which is also
a disadvantage, in a way, because if you try to run that code nothing


function strdup(str) {
    /* proxy for native symbol g_strdup(); */

So, it's not 100% exact, but I was going for the same sort of thing. Better suggestions are welcome.

> Again thanks for doing this. I look forward to see a quick write out how the
> docs are generated.

You can see the Makefile in gjs-documentation for now, it's fairly simple.

desktop-devel-list mailing list
desktop-devel-list gnome org


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