GNOME Bugzilla – Bug 724735
Improve the Gjs documentation generator
Last modified: 2015-02-07 16:55:43 UTC
Jasper asked me to take a look and this is a first stab. The documentation is not great because it's not well organized, and the formatting is poor too, but at least it's correct and complete now.
Created attachment 269699 [details] [review] ast: make sure that all nodes have a namespaces Include Fields (which are not really Node, but the doctool wants to treat as such) and the anonymous node inside them.
Created attachment 269700 [details] [review] doctool: improve Gjs documentation - Add documentation for structures, fields, constants and callbacks - Improve the synopsis for interfaces to have prerequisites and known implementations - Respect gjs constraints for field writability - Format in and out parameters for callables according to GJS conventions - Format property names according to the GJS API - Show boxed constructors according to how they can be used in the gjs API
Created attachment 269701 [details] [review] doctemplates: improve the whitespace in generated pages The main advantage is that we avoid trailing space, so we can take the generated files, mv to -expected and not have the pre-commit hook complain. The other advantage is also readability of the generated sources, in case someone needs to debug the tool.
Can't attach the patch that updates the test, it's too large. It's a mechanical update anyway.
You can see the results of this work at https://people.gnome.org/~gcampagna/docs/ Gio-2.0 and GLib-2.0 are completely generated, while GObject-2.0 is generated and then massaged manually to include pages for GObject.Class and GObject.prototype.connect/disconnect. My plan is to extend them to cover all gjs overrides, and once they're ready they can be moved somewhere in developer.gnome.org.
Review of attachment 269699 [details] [review]: ::: giscanner/ast.py @@ +417,3 @@ self.symbols[fn.symbol] = fn + for f in node.fields: + f.namespace = self I really don't like expandos as a general rule. Can we also add "namespace" as a real property to Field?
Review of attachment 269700 [details] [review]: Go directly to git commit - do not pass Go, do not collect $200.
Review of attachment 269701 [details] [review]: Ok.
Attachment 269699 [details] pushed as bd4608b - ast: make sure that all nodes have a namespaces Attachment 269700 [details] pushed as 75d25b7 - doctool: improve Gjs documentation (The other one was squashed because I made a minor mess to ensure bisectability...)
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]