doxygen.xsl revision 677833bc953b6cb418c701facbdcf4aa18d6c44e
<?xml version="1.0"?>
<!--
* A template to generate a generic IDL file from the generic interface
* definition expressed in XML. The generated file is intended solely to
* generate the documentation using Doxygen.
* Copyright (C) 2006 InnoTek Systemberatung GmbH
*
* This file is part of VirtualBox Open Source Edition (OSE), as
* available from http://www.virtualbox.org. This file is free software;
* General Public License as published by the Free Software Foundation,
* in version 2 as it comes in the "COPYING" file of the VirtualBox OSE
* distribution. VirtualBox OSE is distributed in the hope that it will
* be useful, but WITHOUT ANY WARRANTY of any kind.
*
* If you received this file as part of a commercial VirtualBox
* distribution, then only the terms of your commercial VirtualBox
* license agreement apply instead of the previous paragraph.
-->
<xsl:output method="html" indent="yes"/>
<xsl:strip-space elements="*"/>
<!--
// helper definitions
/////////////////////////////////////////////////////////////////////////////
-->
<!--
* uncapitalizes the first letter only if the second one is not capital
* otherwise leaves the string unchanged
-->
<xsl:template name="uncapitalize">
<xsl:param name="str" select="."/>
<xsl:choose>
<xsl:when test="not(contains('ABCDEFGHIJKLMNOPQRSTUVWXYZ', substring($str,2,1)))">
<xsl:value-of select="
concat(
translate(substring($str,1,1),'ABCDEFGHIJKLMNOPQRSTUVWXYZ','abcdefghijklmnopqrstuvwxyz'),
substring($str,2)
)
"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="string($str)"/>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
<!--
* translates the string to uppercase
-->
<xsl:template name="uppercase">
<xsl:param name="str" select="."/>
<xsl:value-of select="
translate($str,'abcdefghijklmnopqrstuvwxyz','ABCDEFGHIJKLMNOPQRSTUVWXYZ')
"/>
</xsl:template>
<!--
// Doxygen transformation rules
/////////////////////////////////////////////////////////////////////////////
-->
<!--
* all text elements that are not explicitly matched are normalized
* (all whitespace chars are converted to single spaces)
-->
<!--xsl:template match="desc//text()">
<xsl:value-of select="concat(' ',normalize-space(.),' ')"/>
</xsl:template-->
<!--
* all elements that are not explicitly matched are considered to be html tags
* and copied w/o modifications
-->
<xsl:template match="desc//*">
<xsl:copy>
<xsl:apply-templates/>
</xsl:copy>
</xsl:template>
<!--
* paragraph
-->
<xsl:template match="desc//p">
<xsl:text>
</xsl:text>
<xsl:apply-templates/>
<xsl:text>
</xsl:text>
</xsl:template>
<!--
* link
-->
<xsl:template match="desc//link">
<xsl:text>@link </xsl:text>
<!--
* sometimes Doxygen is stupid and cannot resolve global enums properly,
* thinking they are members of the current class. Fix it by adding ::
* in front of any @to value that doesn't start with #.
-->
<xsl:choose>
<xsl:when test="not(starts-with(@to, '#')) and not(contains(@to, '::'))">
<xsl:text>::</xsl:text>
</xsl:when>
</xsl:choose>
<!--
* Doxygen doesn't understand autolinks like Class::func() if Class
* doesn't actually contain a func with no arguments. Fix it.
-->
<xsl:choose>
<xsl:when test="substring(@to, string-length(@to)-1)='()'">
<xsl:value-of select="substring-before(@to, '()')"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="@to"/>
</xsl:otherwise>
</xsl:choose>
<xsl:text> </xsl:text>
<xsl:choose>
<xsl:when test="normalize-space(text())">
<xsl:value-of select="normalize-space(text())"/>
</xsl:when>
<xsl:otherwise>
<xsl:choose>
<xsl:when test="starts-with(@to, '#')">
<xsl:value-of select="substring-after(@to, '#')"/>
</xsl:when>
<xsl:when test="starts-with(@to, '::')">
<xsl:value-of select="substring-after(@to, '::')"/>
</xsl:when>
<xsl:otherwise>
<xsl:value-of select="@to"/>
</xsl:otherwise>
</xsl:choose>
</xsl:otherwise>
</xsl:choose>
<xsl:text>@endlink</xsl:text>
<!--
* insert a dummy empty B element to distinctly separate @endlink
* from the following text
-->
<xsl:element name="b"/>
</xsl:template>
<!--
* note
-->
<xsl:text>
@note </xsl:text>
<xsl:apply-templates/>
<xsl:text>
</xsl:text>
</xsl:template>
<!--
* see
-->
<xsl:text>
@see </xsl:text>
<xsl:apply-templates/>
<xsl:text>
</xsl:text>
</xsl:template>
<!--
* comment for interfaces
-->
<xsl:text>/**
</xsl:text>
<xsl:apply-templates select="text() | *[not(self::note or self::see)]"/>
<xsl:apply-templates select="note"/>
<xsl:apply-templates select="see"/>
@par Interface ID:
<tt>{<xsl:call-template name="uppercase">
<xsl:with-param name="str" select="../@uuid"/>
</xsl:call-template>}</tt>
<xsl:text>
*/
</xsl:text>
</xsl:template>
<!--
* comment for attributes
-->
<xsl:text>/**
</xsl:text>
<xsl:apply-templates select="text() | *[not(self::note or self::see)]"/>
<xsl:apply-templates select="note"/>
<xsl:apply-templates select="see"/>
<xsl:text>
*/
</xsl:text>
</xsl:template>
<!--
* comment for methods
-->
<xsl:text>/**
</xsl:text>
<xsl:apply-templates select="text() | *[not(self::note or self::see)]"/>
<xsl:apply-templates select="desc"/>
</xsl:for-each>
<xsl:apply-templates select="note"/>
<xsl:apply-templates select="see"/>
<xsl:text>
*/
</xsl:text>
</xsl:template>
<!--
* comment for method parameters
-->
<xsl:text>
@param </xsl:text>
<xsl:value-of select="../@name"/>
<xsl:text> </xsl:text>
<xsl:apply-templates select="text() | *[not(self::note or self::see)]"/>
<xsl:text>
</xsl:text>
</xsl:template>
<!--
* comment for interfaces
-->
<xsl:text>/**
</xsl:text>
<xsl:apply-templates select="text() | *[not(self::note or self::see)]"/>
<xsl:apply-templates select="note"/>
<xsl:apply-templates select="see"/>
@par Interface ID:
<tt>{<xsl:call-template name="uppercase">
<xsl:with-param name="str" select="../@uuid"/>
</xsl:call-template>}</tt>
<xsl:text>
*/
</xsl:text>
</xsl:template>
<!--
* comment for enum values
-->
<xsl:text>/** @brief </xsl:text>
<xsl:apply-templates select="text() | *[not(self::note or self::see)]"/>
<xsl:apply-templates select="note"/>
<xsl:apply-templates select="see"/>
<xsl:text>
*/
</xsl:text>
</xsl:template>
<!--
// templates
/////////////////////////////////////////////////////////////////////////////
-->
<!--
* header
-->
<xsl:template match="/idl">
/*
* DO NOT EDIT.
*
* This IDL is automatically generated from the generic interface definition
* using some generic OMG IDL-like syntax SOLELY for the purpose of generating
* the documentation using Doxygen and is not syntactically valid.
*
* DO NOT USE THIS HEADER IN ANY OTHER WAY!
*/
/** @mainpage
*
* This documentation describes all public COM interfaces and components
* provided by the VirtualBox server and by the VirtualBox client library.
* Together, these interfaces and components comprise the so-called
* <i>VirtualBox Main API</i> intended to control both the VirtualBox server
* process and processes executing individual virtual machines using
* COM techniques.
*
* On Windows platforms, the VirtualBox Main API uses Microsoft COM, a native COM
* implementation. On all other platforms, Mozilla XPCOM, an open-source COM
* implementation, is used.
*
* @note The source IDL file (VirtualBox.idl) this documentation refers to is
* automatically generated from the generic interface definition file (used
* to define all interfaces in a platform-independent way) and uses some generic
* OMG IDL-like syntax <b>solely</b> for the purpose of generating this
* platform-independent documentation. This generated file is not a syntactically
* valid IDL file and <b>must not</b> be used for programming.
*
* @todo Later, the documentation will contain platform-dependent IDL and C++
* prototypes of methods of all interfaces, for convenience.
*
* @todo Some interfaces are completely platform-specific. This will be also
* mentioned in the documentation.
*/
<xsl:text>
</xsl:text>
<xsl:apply-templates/>
</xsl:template>
<!--
* accept all <if>s
-->
<xsl:template match="if">
<xsl:apply-templates/>
</xsl:template>
<!--
* cpp_quote (ignore)
-->
<xsl:template match="cpp">
</xsl:template>
<!--
* #ifdef statement (@if attribute)
-->
<xsl:template match="@if" mode="begin">
<xsl:text>#if </xsl:text>
<xsl:value-of select="."/>
<xsl:text>
</xsl:text>
</xsl:template>
<xsl:template match="@if" mode="end">
<xsl:text>#endif
</xsl:text>
</xsl:template>
<!--
* libraries
-->
<xsl:template match="module">
<!-- all enums go first -->
<!-- everything else but enums -->
<xsl:apply-templates select="*[not(self::enum) and not(self::if[enum])]"/>
</xsl:template>
<!--
* interfaces
-->
<xsl:template match="interface">
<xsl:apply-templates select="desc"/>
<xsl:text>interface </xsl:text>
<xsl:value-of select="@name"/>
<xsl:text> : </xsl:text>
<xsl:value-of select="@extends"/>
<xsl:text>
{
</xsl:text>
<!-- attributes (properties) -->
<xsl:apply-templates select="attribute"/>
<!-- methods -->
<xsl:apply-templates select="method"/>
<!-- 'if' enclosed elements, unsorted -->
<xsl:apply-templates select="if"/>
<!-- -->
<xsl:text>}; /* interface </xsl:text>
<xsl:value-of select="@name"/>
<xsl:text> */

</xsl:text>
</xsl:template>
<!--
* attributes
-->
<xsl:template match="interface//attribute | collection//attribute">
<xsl:apply-templates select="@if" mode="begin"/>
<xsl:apply-templates select="desc"/>
<xsl:text> </xsl:text>
<xsl:if test="@readonly='yes'">
<xsl:text>readonly </xsl:text>
</xsl:if>
<xsl:text>attribute </xsl:text>
<xsl:apply-templates select="@type"/>
<xsl:text> </xsl:text>
<xsl:value-of select="@name"/>
<xsl:text>;
</xsl:text>
<xsl:apply-templates select="@if" mode="end"/>
<xsl:text>
</xsl:text>
</xsl:template>
<!--
* methods
-->
<xsl:template match="interface//method | collection//method">
<xsl:apply-templates select="@if" mode="begin"/>
<xsl:apply-templates select="desc"/>
<xsl:text> void </xsl:text>
<xsl:value-of select="@name"/>
<xsl:if test="param">
<xsl:text> (
</xsl:text>
<xsl:for-each select="param [position() != last()]">
<xsl:text> </xsl:text>
<xsl:apply-templates select="."/>
<xsl:text>,
</xsl:text>
</xsl:for-each>
<xsl:text> </xsl:text>
<xsl:apply-templates select="param [last()]"/>
<xsl:text>
 );
</xsl:text>
</xsl:if>
<xsl:if test="not(param)">
<xsl:text>();
</xsl:text>
</xsl:if>
<xsl:apply-templates select="@if" mode="end"/>
<xsl:text>
</xsl:text>
</xsl:template>
<!--
* co-classes
-->
<xsl:template match="class">
<!-- class and contract id: later -->
<!-- CLSID_xxx declarations for XPCOM, for compatibility with Win32: later -->
</xsl:template>
<!--
* enumerators
-->
<xsl:template match="enumerator">
<xsl:text>interface </xsl:text>
<xsl:value-of select="@name"/>
<xsl:text> : $unknown
{
</xsl:text>
<!-- HasMore -->
<xsl:text> void hasMore ([retval] out boolean more);

</xsl:text>
<!-- GetNext -->
<xsl:text> void getNext ([retval] out </xsl:text>
<xsl:apply-templates select="@type"/>
<xsl:text> next);

</xsl:text>
<!-- -->
<xsl:text>}; /* interface </xsl:text>
<xsl:value-of select="@name"/>
<xsl:text> */

</xsl:text>
</xsl:template>
<!--
* collections
-->
<xsl:template match="collection">
<xsl:if test="not(@readonly='yes')">
<xsl:message terminate="yes">
<xsl:value-of select="concat(@name,': ')"/>
<xsl:text>non-readonly collections are not currently supported</xsl:text>
</xsl:message>
</xsl:if>
<xsl:text>interface </xsl:text>
<xsl:value-of select="@name"/>
<xsl:text> : $unknown
{
</xsl:text>
<!-- Count -->
<xsl:text> readonly attribute unsigned long count;

</xsl:text>
<!-- GetItemAt -->
<xsl:text> void getItemAt (in unsigned long index, [retval] out </xsl:text>
<xsl:apply-templates select="@type"/>
<xsl:text> item);

</xsl:text>
<!-- Enumerate -->
<xsl:text> void enumerate ([retval] out </xsl:text>
<xsl:apply-templates select="@enumerator"/>
<xsl:text> enumerator);

</xsl:text>
<!-- other extra attributes (properties) -->
<xsl:apply-templates select="attribute"/>
<!-- other extra methods -->
<xsl:apply-templates select="method"/>
<!-- 'if' enclosed elements, unsorted -->
<xsl:apply-templates select="if"/>
<!-- -->
<xsl:text>}; /* interface </xsl:text>
<xsl:value-of select="@name"/>
<xsl:text> */

</xsl:text>
</xsl:template>
<!--
* enums
-->
<xsl:template match="enum">
<xsl:apply-templates select="desc"/>
<xsl:text>enum </xsl:text>
<xsl:value-of select="@name"/>
<xsl:text>
{
</xsl:text>
<xsl:for-each select="const">
<xsl:apply-templates select="desc"/>
<xsl:text> </xsl:text>
<xsl:value-of select="@name"/> = <xsl:value-of select="@value"/>
<xsl:text>,
</xsl:text>
</xsl:for-each>
<xsl:text>};

</xsl:text>
</xsl:template>
<!--
* method parameters
-->
<xsl:if test="@array">
<xsl:if test="@dir='return'">
<xsl:message terminate="yes">
<xsl:value-of select="concat(../../@name,'::',../@name,'::',@name,': ')"/>
<xsl:text>return array parameters are not currently supported</xsl:text>
</xsl:message>
</xsl:if>
<xsl:text>[array, </xsl:text>
<xsl:choose>
<xsl:message terminate="yes">
<xsl:value-of select="concat(../../@name,'::',../@name,': ')"/>
<xsl:text> must have the same direction</xsl:text>
</xsl:message>
</xsl:if>
<xsl:text>size_is(</xsl:text>
<xsl:if test="@dir='out'">
<xsl:text>, </xsl:text>
</xsl:if>
<xsl:text>*</xsl:text>
</xsl:if>
<xsl:value-of select="@array"/>
<xsl:text>)</xsl:text>
</xsl:when>
<xsl:otherwise>
<xsl:message terminate="yes">
<xsl:value-of select="concat(../../@name,'::',../@name,'::',@name,': ')"/>
<xsl:text>array attribute refers to non-existent param: </xsl:text>
<xsl:value-of select="@array"/>
</xsl:message>
</xsl:otherwise>
</xsl:choose>
<xsl:text>] </xsl:text>
</xsl:if>
<xsl:choose>
<xsl:when test="@dir='in'">in </xsl:when>
<xsl:when test="@dir='out'">out </xsl:when>
<xsl:when test="@dir='return'">[retval] out </xsl:when>
<xsl:otherwise>in</xsl:otherwise>
</xsl:choose>
<xsl:apply-templates select="@type"/>
<xsl:text> </xsl:text>
<xsl:value-of select="@name"/>
</xsl:template>
<!--
-->
<xsl:template match="
attribute/@type | param/@type |
enumerator/@type | collection/@type | collection/@enumerator
">
<xsl:variable name="self_target" select="current()/ancestor::if/@target"/>
<xsl:choose>
<!-- standard types -->
<xsl:when test=".='result'">result</xsl:when>
<xsl:when test=".='boolean'">boolean</xsl:when>
<xsl:when test=".='octet'">octet</xsl:when>
<xsl:when test=".='short'">short</xsl:when>
<xsl:when test=".='unsigned short'">unsigned short</xsl:when>
<xsl:when test=".='long'">long</xsl:when>
<xsl:when test=".='long long'">long long</xsl:when>
<xsl:when test=".='unsigned long'">unsigned long</xsl:when>
<xsl:when test=".='unsigned long long'">unsigned long long</xsl:when>
<xsl:when test=".='char'">char</xsl:when>
<xsl:when test=".='wchar'">wchar</xsl:when>
<xsl:when test=".='string'">string</xsl:when>
<xsl:when test=".='wstring'">wstring</xsl:when>
<!-- UUID type -->
<xsl:when test=".='uuid'">uuid</xsl:when>
<!-- system interface types -->
<xsl:when test=".='$unknown'">$unknown</xsl:when>
<xsl:otherwise>
<xsl:choose>
<!-- enum types -->
<xsl:when test="
">
<xsl:value-of select="."/>
</xsl:when>
<!-- custom interface types -->
<xsl:when test="
(name(current())='enumerator' and
((ancestor::module/enumerator[@name=current()]) or
) or
) or
((ancestor::module/collection[@name=current()]) or
)
">
<xsl:value-of select="."/>
</xsl:when>
<!-- other types -->
<xsl:otherwise>
<xsl:message terminate="yes">
<xsl:text>Unknown parameter type: </xsl:text>
<xsl:value-of select="."/>
</xsl:message>
</xsl:otherwise>
</xsl:choose>
</xsl:otherwise>
</xsl:choose>
</xsl:template>
</xsl:stylesheet>