Some API reference documentation, such as this http://telepathy.freedesktop.org/doc/telepathy-glib/telepathy-glib-connection-manager.html#tp-cli-connection-manager-call-request-connection contain huge amounts of weird markup, making it unreadable. For instance, " <tp:docstring xmlns="http://www.w3.org/1999/xhtml"> <p>Request a <tp:dbus-ref namespace="org.freedesktop.Telepathy">Connection</tp:dbus-ref> object representing a given account on a given protocol with the given parameters. "
*** Bug 32079 has been marked as a duplicate of this bug. ***
This is harder to fix than you might think, because the D-Bus API documentation is in HTML + extensions, whereas the telepathy-glib API reference is in Docbook-embedded-in-comments (gtk-doc). The tools that generate the C code (glib-client-gen.py and glib-ginterface-gen.py) would have to be adapted to: * turn the Telepathy-specific extensions into HTML (we already have code to do this, although hyperlinks would need adjusting - making them point to the online copy of the D-Bus API docs would probably be enough) * turn HTML (or at least the subset of it that we actually use) into Docbook markup * put that Docbook markup in the comments that gtk-doc parses When this bug was originally filed, we used XSLT for the code generation, so doing that was basically impossible (XSLT is unsuitable for Perl-style text-mangling). We now use Python, so it may be possible to solve this, but it'd still be rather awkward (unless someone's already written a HTML-subset-to-Docbook converter that we can use?). Porting the code-generation tools to use specparser.py rather than parsing it themselves is a prerequisite for this, IMO.
-- GitLab Migration Automatic Message -- This bug has been migrated to freedesktop.org's GitLab instance and has been closed from further activity. You can subscribe and participate further through the new bug through this link to our GitLab instance: https://gitlab.freedesktop.org/telepathy/telepathy-glib/issues/8.
Use of freedesktop.org services, including Bugzilla, is subject to our Code of Conduct. How we collect and use information is described in our Privacy Policy.