4:27 p.m.
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-ba...
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
5:23 p.m.
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(a)redhat.com +1-801-349-2682
Libvirt virtualization library http://libvirt.org
8:13 a.m.
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(a)veillard.com | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library http://libvirt.org/
5247
days inactive
5249
days old
2 comments
3 participants
participants (3)
-
Daniel Veillard -
Eric Blake -
Justin Clift