[libvirt] Suggestions on how to add "Available from version: 0.x.x"?

[Daniel Veillard]

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 at veillard.com  | Rpmfind RPM search engine http://rpmfind.net/
http://veillard.com/ | virtualization library  http://libvirt.org/