[libvirt] Suggestions on how to add "Available from version: 0.x.x"?
Hi all, Looking at how to add extra info to the API docs. Specifically, listing with each function the version of libvirt it became available in. As is done with the GLib/GTK docs. Example here: http://library.gnome.org/devel/glib/stable/glib-Base64-Encoding.html#g-base6... Looking at our present API docs though, they seem to be autogenerated, so I'm no sure how to approach this. My initial thinking is maybe having the list of each function per version in a separate (text?) file, and then somehow pull that info in. But, not even sure that will work. Anyone have ideas? Regards and best wishes, Justin Clift
On 07/10/2010 03:27 PM, Justin Clift wrote:
Looking at our present API docs though, they seem to be autogenerated, so I'm no sure how to approach this.
My initial thinking is maybe having the list of each function per version in a separate (text?) file, and then somehow pull that info in.
We already have one file that lists when each API was added (src/libvirt_public.syms).
But, not even sure that will work.
Anyone have ideas?
Hmm - our autogenerated docs are already modeled after doxygen/javadoc style comments. Doesn't javadoc support the @since tag? If that is the case, it would be pretty easy to document @since alongside all the other comments that turn into the autogenerated text, and much easier to maintain in contrast to any solution which requires maintaining multiple files when adding a new API. -- Eric Blake eblake@redhat.com +1-801-349-2682 Libvirt virtualization library http://libvirt.org
On Sat, Jul 10, 2010 at 04:23:32PM -0600, Eric Blake wrote:
On 07/10/2010 03:27 PM, Justin Clift wrote:
Looking at our present API docs though, they seem to be autogenerated, so I'm no sure how to approach this.
My initial thinking is maybe having the list of each function per version in a separate (text?) file, and then somehow pull that info in.
We already have one file that lists when each API was added (src/libvirt_public.syms).
But, not even sure that will work.
Anyone have ideas?
Hmm - our autogenerated docs are already modeled after doxygen/javadoc style comments. Doesn't javadoc support the @since tag? If that is the case, it would be pretty easy to document @since alongside all the other comments that turn into the autogenerated text, and much easier to maintain in contrast to any solution which requires maintaining multiple files when adding a new API.
Something I added in libxml2 recently is a symbol XML file like: paphio:~/XML -> tail -20 doc/symbols.xml <release version="2.6.32"> <symbol file="schematron">xmlSchematronSetValidStructuredErrors</symbol> </release> <release version="2.7.0"> <symbol file="xmlmemory">xmlMemDisplayLast</symbol> <symbol file="entities">xmlNewEntity</symbol> <symbol file="xmlschemas">xmlSchemaValidCtxtGetParserCtxt</symbol> </release> <release version="2.7.3"> <symbol file="tree">xmlChildElementCount</symbol> <symbol file="tree">xmlFirstElementChild</symbol> <symbol file="tree">xmlLastElementChild</symbol> <symbol file="tree">xmlNextElementSibling</symbol> <symbol file="tree">xmlPreviousElementSibling</symbol> </release> <release version="2.7.4"> <symbol file="globals">xmlStructuredErrorContext</symbol> <symbol file="xinclude">xmlXIncludeProcessTreeFlagsData</symbol> </release> </symbols> paphio:~/XML -> then based on that 1/ the symbol file used by the linker can be autogenerated, and also the versioning informations are used when generating the docs from docs/libxml2-api.xml. The XSLT also check for missing or extra symbols which allow for more automated check of potentially missing exported symbols. Maybe some of that could be plugged back into libvirt too. That keeps it out of the source file but on the other hand that's not supposed to change over time and allow this to be used for more checking when I assemble a release. Daniel -- Daniel Veillard | libxml Gnome XML XSLT toolkit http://xmlsoft.org/ daniel@veillard.com | Rpmfind RPM search engine http://rpmfind.net/ http://veillard.com/ | virtualization library http://libvirt.org/
participants (3)
-
Daniel Veillard -
Eric Blake -
Justin Clift