GNOME Bugzilla – Bug 683046
Add mallard documentation for GJS
Last modified: 2015-02-07 16:47:03 UTC
My plan was to wait 3.7.1 before making this public, but seeing that other people are working on it, and to avoid stepping on each other toes, here it is what I obtained so far. It can be considered ready for review, although it's just a first start on the bigger feature of decent JS docs.
Created attachment 222955 [details] [review] Namespace: fix appending of nodes Traverse appended nodes for methods, so that namespace.symbols contains all known symbols and not just global functions. Also, ensure that all relevant nodes are appended when parsing GIRs.
Created attachment 222956 [details] [review] Ast: Add parent to Fields Properties have it, there is no reason for Field not to, and in this way mallard docs can treat a field almost like a property.
Created attachment 222957 [details] [review] Add documentation for enumeration members Enum members were Annotated in the AST, and most code already assumed they could have docs. What was missing was reading the docs from the comment blocks and writing them in the XML.
Created attachment 222958 [details] [review] MallardWriter: support cross-references across namespaces Look in included namespaces when resolving a cross-reference.
Created attachment 222959 [details] [review] MallardWriter: don't fail if a language doesn't have a specific template Different languages have different level of support for the docs, and thus some may miss one template if recently add. If that's the case, silently fall back to the default template.
Created attachment 222960 [details] [review] Add documentation for gjs JS bindings Add the necessary templates and a MallardFormatter subclass to handle JS bindings. The docs are intentionally specific to gjs, as they make some assumption on the way the binding presents the API, such as which function arguments are in or out, which fields are writable, which structures can be constructed with operator new, etc.
Created attachment 222961 [details] [review] Expand on the documentation tests Add tests for complex function signatures (including arrays and callbacks), for enumerations and for static methods. Add JS reference files.
Review of attachment 222957 [details] [review]: Looks good.
Review of attachment 222956 [details] [review]: Makes sense.
Review of attachment 222958 [details] [review]: Yep.
Review of attachment 222959 [details] [review]: I'm not sure it's not an error to do this. I'd also like to see templates in subdirectories, so +0 on this patch.
Review of attachment 222960 [details] [review]: I'd really like to clean up the doctool architecture before landing something like this. This was written before doctool was scrapped and templates were introduced, but I still think achieving an architecture like this would be useful: https://github.com/magcius/gobject-introspection/commit/3d36e1f8a0d08311669023a72a2441775471ec28
Review of attachment 222961 [details] [review]: Would you mind dropping the JS stuff for now and pushing this early?
(In reply to comment #13) > Review of attachment 222961 [details] [review]: > > Would you mind dropping the JS stuff for now and pushing this early? Ok. What about patch 222955?
I was hoping to defer to Colin or Johan to review that one. On a brief look, it's fine, but they have more knowledge of the hairy scanner code than I.
Review of attachment 222955 [details] [review]: Looks correct to me.
Attachment 222955 [details] pushed as 9ff28e6 - Namespace: fix appending of nodes Attachment 222956 [details] pushed as b7e230a - Ast: Add parent to Fields Attachment 222957 [details] pushed as d893890 - Add documentation for enumeration members Attachment 222958 [details] pushed as 7fc2e9d - MallardWriter: support cross-references across namespaces Attachment 222961 [details] pushed as ce4a25d - Expand on the documentation tests
Is there anything left from this bug?
Not really, I'd say.
[Mass-moving gobject-introspection tickets to its own Bugzilla product - see bug 708029. Mass-filter your bugmail for this message: introspection20150207 ]