Re: [PATCH] NM DBUS api documentation build system
On Thursday 28 February 2008 03:09:27 Dan Williams wrote: Committed with a few cleanups, thanks! Nice! I've got some documentation for the various Settings keys and types here in my git - documentation progress hasn't stopped, but I need to make some progress here on my KDE 4 client before tidying it up for you. Will -- Will Stephenson IRC: Bille ___ NetworkManager-list mailing list NetworkManager-list@gnome.org http://mail.gnome.org/mailman/listinfo/networkmanager-list
Re: [PATCH] NM DBUS api documentation build system
On Mon, 2008-02-11 at 23:07 +0100, Will Stephenson wrote: On Monday 11 February 2008 17:27:53 Dan Williams wrote: On Mon, 2008-02-11 at 17:26 +0100, Will Stephenson wrote: On Friday 08 February 2008, Dan Williams said: So a simple patch to dbus-binding-tool to make it ignore namespaced nodes and attributes will allow us to use the TP namespace within the existing introspection XML files and avoid the extra step of spec/*. Ack, maybe it does so already - but is the extra spec/* step really worse than having all of downstream have to use a patched dbus-binding-tool? The patch for dbus-glib is the right thing to do anyway; and I don't think there's a really good reason to have the extra step either. If the fix does get into dbus-glib, we'd just have to rework the spec generation code again, so we might as well do it right the first time IMHO. I'm still not quite sure it's good to pass around extended introspection xml. Are you able to you check the python bindings' behaviour? I'll see what the Qt tools do. If you're still willing to work on this, I'd love a patch that would run the XSLT stuff over the introspection/*.xml (feel free to add all.xml to introspection/* if you like) and generate the HTML docs. I don't think it would be to much work to modify the makefile stuff to rip out the bits that convert spec/* - introspection/* and just preserve the bits that do introspection/* - HTML, right? It's trivial - will post a patch shortly. Patch attached. Committed with a few cleanups, thanks! Dan ___ NetworkManager-list mailing list NetworkManager-list@gnome.org http://mail.gnome.org/mailman/listinfo/networkmanager-list
Re: [PATCH] NM DBUS api documentation build system
On Mon, 2008-02-11 at 23:07 +0100, Will Stephenson wrote: On Monday 11 February 2008 17:27:53 Dan Williams wrote: On Mon, 2008-02-11 at 17:26 +0100, Will Stephenson wrote: On Friday 08 February 2008, Dan Williams said: So a simple patch to dbus-binding-tool to make it ignore namespaced nodes and attributes will allow us to use the TP namespace within the existing introspection XML files and avoid the extra step of spec/*. Ack, maybe it does so already - but is the extra spec/* step really worse than having all of downstream have to use a patched dbus-binding-tool? The patch for dbus-glib is the right thing to do anyway; and I don't think there's a really good reason to have the extra step either. If the fix does get into dbus-glib, we'd just have to rework the spec generation code again, so we might as well do it right the first time IMHO. I'm still not quite sure it's good to pass around extended introspection xml. Are you able to you check the python bindings' behaviour? I'll see what the Qt tools do. Well, remember that dbus-glib _doesn't_ take the *.xml verbatim and pass it through the bus. The *.xml files are processed into a custom syntax and stuffed into the C code. You don't really need the property types for example, because the glib code is able to introspect the property types directly from the GObject itself. So I'm not sure why other bindings are relevant here, because none of the namespaced stuff should ever go over the bus at all. If you're still willing to work on this, I'd love a patch that would run the XSLT stuff over the introspection/*.xml (feel free to add all.xml to introspection/* if you like) and generate the HTML docs. I don't think it would be to much work to modify the makefile stuff to rip out the bits that convert spec/* - introspection/* and just preserve the bits that do introspection/* - HTML, right? It's trivial - will post a patch shortly. Patch attached. Will review, thanks! Dan ___ NetworkManager-list mailing list NetworkManager-list@gnome.org http://mail.gnome.org/mailman/listinfo/networkmanager-list
Re: [PATCH] NM DBUS api documentation build system
On Mon, 2008-02-11 at 17:26 +0100, Will Stephenson wrote: On Friday 08 February 2008, Dan Williams said: So a simple patch to dbus-binding-tool to make it ignore namespaced nodes and attributes will allow us to use the TP namespace within the existing introspection XML files and avoid the extra step of spec/*. Ack, maybe it does so already - but is the extra spec/* step really worse than having all of downstream have to use a patched dbus-binding-tool? The patch for dbus-glib is the right thing to do anyway; and I don't think there's a really good reason to have the extra step either. If the fix does get into dbus-glib, we'd just have to rework the spec generation code again, so we might as well do it right the first time IMHO. If you're still willing to work on this, I'd love a patch that would run the XSLT stuff over the introspection/*.xml (feel free to add all.xml to introspection/* if you like) and generate the HTML docs. I don't think it would be to much work to modify the makefile stuff to rip out the bits that convert spec/* - introspection/* and just preserve the bits that do introspection/* - HTML, right? It's trivial - will post a patch shortly. Great! Thanks! You're welcome. And this time, I trained my spam filter on your mail ;). It is nice to have a unified overview of the API. Thanks again. Dan ___ NetworkManager-list mailing list NetworkManager-list@gnome.org http://mail.gnome.org/mailman/listinfo/networkmanager-list
Re: [PATCH] NM DBUS api documentation build system
On Tuesday 05 February 2008 22:27:28 Dan Williams wrote: We definitely need the docs, the only question is how exactly to go about getting them. Sorry, I just found your replies now in my spam trap after Marcel's response indicated you'd replied... I'm working on reading the code and adding documentation to it as I go now. It's taking a while but I hope to have a patch in the next couple of days. Will -- Will Stephenson IRC: Bille ___ NetworkManager-list mailing list NetworkManager-list@gnome.org http://mail.gnome.org/mailman/listinfo/networkmanager-list
Re: [PATCH] NM DBUS api documentation build system
On Wednesday 06 February 2008 15:56:32 Dan Williams wrote: On Wed, 2008-02-06 at 09:20 +0100, Will Stephenson wrote: On Tuesday 05 February 2008 20:55:33 Marcel Holtmann wrote: Hi Will, I must agree here. Something that generate the introspection is not helpful at all. It is hard enough to keep external introspection XML files in sync with the actual runtime introspection. Surely the glib binding generators create the runtime introspection from the xml files? That's the way the Qt bindings work. no they don't. In the dbus-glib case you have the a pre-processing step that uses the XML file to generate glue code. You attach this to a GObject and then the bindings generate the runtime introspection from the runtime information of the object. You could do it without the XML file if you really want to. As far as I can tell looking at dbus-glib, the xml returned by Introspect() is generated at runtime from object info statically generated in the glue code from the introspection xml files. Therefore the introspection xml files are the original source of the interfaces offered by the objects, therefore these are the places where documentation is most effective. I'm trying to document the actual implementation of NM 0.7. I'm aware that it's possible to do all this by hand or write a program that doesn't actually implement the interface it advertises but those are just hypothetical counter-examples. Yeah; the docs, the introspection data, and the generated bindings all need to come from the same place, and that all needs to be done automatically. I don't want to manually update 3 places. Where do the current introspection/*.xml files go in your scheme? The diff removes them but doesn't apparently add anything back that would describe the interfaces. The files in introspection/*.xml move to spec/ Will -- Will Stephenson IRC: Bille ___ NetworkManager-list mailing list NetworkManager-list@gnome.org http://mail.gnome.org/mailman/listinfo/networkmanager-list
Re: [PATCH] NM DBUS api documentation build system
On Friday 08 February 2008 17:52:22 Dan Williams wrote: On Tue, 2008-02-05 at 15:46 +0100, Will Stephenson wrote: Here's a patch that adds api documentation generation to the NM build system. The code is taken from the Telepathy project. I think as others have expressed, I think that process adds an extra, unnecessary step. I think I'd rather see the following: 1) annotate the introspection/*.xml files using the many-times-proposed org.freedesktop.DBus.Doc annotation name which was designed just for this. You'd end up with stuff looking like this: interface name=org.freedesktop.NetworkManager.Device method name=Deactivate annotation name=org.freedesktop.DBus.GLib.CSymbol value=impl_device_deactivate/ annotation name=org.freedesktop.DBus.Doc Deactivates the device, removing applicable routes, IP addresses, and marking the device down. /annotation /method property name=Udi type=s access=read annotation name=org.freedesktop.DBus.Doc The HAL Unique Device Identifier for this device. /annotation /property ... /interface Google knows exactly one hit for org.freedesktop.DBus.Doc, that doesn't say much. Where is this documented? From this example it seems to be less descriptive than Telepathy's format, but I'll reserve judgement until I've had a look at it. If you've got an archive of the dbus list, look for the thread documentation and introspection from Nov 2006 where Simon McVittie compares the tp doc format and another namespaced doc proposal. 2) Assuming dbus-glib's binding tool ignores annotations it doesn't recognize (and if it doesn't, we fix it to do so), the binding tool will just continue as normal creating the glue and bindings file. It should ignore namespaces it doesn't recognise too, making tp: namespaced introspection xml safe even without the (IMO trivial) extra xslt step that removes them. 3) The optional document generation step (enabled at configure-time with --enable-docs or something) can run xslt or something on the introspection XML and generate the HTML documentation. Right, this is how the tp system works too. There are some bits of the code that could stand extra documentation that aren't part of the D-Bus API directly, like the NMSettings subclasses. They are of course D-Bus dictionaries, and the key/value pairs and types are firmly defined. While that spec doesn't live in SVN, it really should live there, and it really should be pulled into the autogenerated docs for consistency. tp uses similar settings dictionaries, and defines their key ranges in these types' docstrings. Have a look at http://telepathy.freedesktop.org/spec.html for its output. Will -- Will Stephenson IRC: Bille ___ NetworkManager-list mailing list NetworkManager-list@gnome.org http://mail.gnome.org/mailman/listinfo/networkmanager-list
Re: [PATCH] NM DBUS api documentation build system
On Feb 5, 2008 8:46 AM, Will Stephenson [EMAIL PROTECTED] wrote: snip I haven't actually added any api documentation yet. I'm working on supporting NM 0.7 in KDE 4 and would do so as I grok 0.7. The patch just replicates the status quo with the ability to add api docs. The system can also add a make check target to assure the docu generation is working but I haven't adapted/copied that yet. Another question is, are you interested in async glib binding support? The system can apparently generate separate async introspection xml but I haven't adapted that either yet as I'm not familiar with the glib bindings. I've tested this locally. Dan, Tambet: what do you think about integrating it? It would make NM client developement much easier. While I'd like to have always up to date documentation, I'm not sure I like this. The patch you sent only removes the introspection XML we currently have and adds some XSLT which I can't read (and thus maintain). It'll make development easier only if someone actually writes that documentation, just converting to more magic makes things harder to understand. And again, I like having documentation as much as anyone, but since we have two developers in total (who are busy with maintenance work for a lot of time), I personally would rather write code. So if anyone wants to help with documentation, it could live in a text file for now. When it has enough information, and if Dan feels comfortable maintaining XSLT, I wouldn't have anything against the proposed solution. Tambet ___ NetworkManager-list mailing list NetworkManager-list@gnome.org http://mail.gnome.org/mailman/listinfo/networkmanager-list
Re: [PATCH] NM DBUS api documentation build system
Hi Tambet, I haven't actually added any api documentation yet. I'm working on supporting NM 0.7 in KDE 4 and would do so as I grok 0.7. The patch just replicates the status quo with the ability to add api docs. The system can also add a make check target to assure the docu generation is working but I haven't adapted/copied that yet. Another question is, are you interested in async glib binding support? The system can apparently generate separate async introspection xml but I haven't adapted that either yet as I'm not familiar with the glib bindings. I've tested this locally. Dan, Tambet: what do you think about integrating it? It would make NM client developement much easier. While I'd like to have always up to date documentation, I'm not sure I like this. The patch you sent only removes the introspection XML we currently have and adds some XSLT which I can't read (and thus maintain). It'll make development easier only if someone actually writes that documentation, just converting to more magic makes things harder to understand. And again, I like having documentation as much as anyone, but since we have two developers in total (who are busy with maintenance work for a lot of time), I personally would rather write code. So if anyone wants to help with documentation, it could live in a text file for now. When it has enough information, and if Dan feels comfortable maintaining XSLT, I wouldn't have anything against the proposed solution. I must agree here. Something that generate the introspection is not helpful at all. It is hard enough to keep external introspection XML files in sync with the actual runtime introspection. Why should we have another thing to maintain. If you could generate the introspection files from within the source code, that is a different story. Something in combination with Doxygen. Regards Marcel ___ NetworkManager-list mailing list NetworkManager-list@gnome.org http://mail.gnome.org/mailman/listinfo/networkmanager-list
