Hi, if you're following git, you may have noticed that Jon and me have quite a few commits that only touch documentation, recently. I thought I should explain here what we this is about: We are trying to improve the developer documentation for application developers.
The reference documentation for the GTK+ stack may be extensive, but it is not easy to navigate and hard to make sense of if you are e.g. writing in JavaScript and are not comfortable translating from C to JavaScript in your head. The need to improve this situation has been discussed repeatedly: at the developer experience hackfest a year ago, and more recently at the Montreal summit. Now its time to do something about it ! Our short-term goals are to - Make the doc comments more readable by moving from clunky docbook markup to markdown. This will help both for reading and updating the documentation in the sources, and for limiting the scope of whar our documentation-generating tools need to parse when generating online docs. - Move from clear-text (like "free with gdk_rgba_free()") to annotations as much as possible, so we don't tell JavaScript developers about memory management. - Add language annotations to embedded examples. - Generate the action (function-level) reference documentation with g-ir-doc-tool from the gir We've started with GTK+ and GLib, but this effort should be easy to extend up and down the stack from here. Help is more than welcome! Matthias
_______________________________________________ desktop-devel-list mailing list [email protected] https://mail.gnome.org/mailman/listinfo/desktop-devel-list
