doxygen.xsl@ 64226

Last change on this file since 64226 was 62486, checked in by vboxsync, 8 years ago
(C) 2016
Property svn:eol-style set to `native` Property svn:keywords set to `Author Date Id Revision`
File size: 19.3 KB

Line
1	<?xml version="1.0"?>
2
3	<!--
4	* A template to generate a generic IDL file from the generic interface
5	* definition expressed in XML. The generated file is intended solely to
6	* generate the documentation using Doxygen.
7
8	Copyright (C) 2006-2016 Oracle Corporation
9
10	This file is part of VirtualBox Open Source Edition (OSE), as
11	available from http://www.virtualbox.org. This file is free software;
12	you can redistribute it and/or modify it under the terms of the GNU
13	General Public License (GPL) as published by the Free Software
14	Foundation, in version 2 as it comes in the "COPYING" file of the
15	VirtualBox OSE distribution. VirtualBox OSE is distributed in the
16	hope that it will be useful, but WITHOUT ANY WARRANTY of any kind.
17	-->
18
19	<xsl:stylesheet version="1.0" xmlns:xsl="http://www.w3.org/1999/XSL/Transform">
20	<xsl:output method="html" indent="yes"/>
21
22	<xsl:strip-space elements="*"/>
23
24	<xsl:include href="typemap-shared.inc.xsl" />
25
26
27	<!--
28	// Doxygen transformation rules
29	/////////////////////////////////////////////////////////////////////////////
30	-->
31
32	<!--
33	* all text elements that are not explicitly matched are normalized
34	* (all whitespace chars are converted to single spaces)
35	-->
36	<!--xsl:template match="desc//text()">
37	<xsl:value-of select="concat(' ',normalize-space(.),' ')"/>
38	</xsl:template-->
39
40	<!--
41	* all elements that are not explicitly matched are considered to be html tags
42	* and copied w/o modifications
43	-->
44	<xsl:template match="desc//*">
45	<xsl:copy>
46	<xsl:apply-templates/>
47	</xsl:copy>
48	</xsl:template>
49
50	<!--
51	* same like desc//* but place <ol> at start of line otherwise Doxygen will not
52	* find it
53	-->
54	<xsl:template match="desc//ol">
55	<xsl:text> </xsl:text>
56	<xsl:copy>
57	<xsl:apply-templates/>
58	</xsl:copy>
59	</xsl:template>
60
61	<!--
62	* same like desc//* but place <ul> at start of line otherwise Doxygen will not
63	* find it
64	-->
65	<xsl:template match="desc//ul">
66	<xsl:text> </xsl:text>
67	<xsl:copy>
68	<xsl:apply-templates/>
69	</xsl:copy>
70	</xsl:template>
71
72	<!--
73	* same like desc//* but place <pre> at start of line otherwise Doxygen will not
74	* find it
75	-->
76	<xsl:template match="desc//pre">
77	<xsl:text> </xsl:text>
78	<xsl:copy>
79	<xsl:apply-templates/>
80	</xsl:copy>
81	</xsl:template>
82
83	<!--
84	* paragraph
85	-->
86	<xsl:template match="desc//p">
87	<xsl:text> </xsl:text>
88	<xsl:apply-templates/>
89	<xsl:text> </xsl:text>
90	</xsl:template>
91
92	<!--
93	* link
94	-->
95	<xsl:template match="desc//link">
96	<xsl:text>@link </xsl:text>
97	<!--
98	* sometimes Doxygen is stupid and cannot resolve global enums properly,
99	* thinking they are members of the current class. Fix it by adding ::
100	* in front of any @to value that doesn't start with #.
101	-->
102	<xsl:choose>
103	<xsl:when test="not(starts-with(@to, '#')) and not(contains(@to, '::'))">
104	<xsl:text>::</xsl:text>
105	</xsl:when>
106	</xsl:choose>
107	<!--
108	* Doxygen doesn't understand autolinks like Class::func() if Class
109	* doesn't actually contain a func with no arguments. Fix it.
110	-->
111	<xsl:choose>
112	<xsl:when test="substring(@to, string-length(@to)-1)='()'">
113	<xsl:value-of select="substring-before(@to, '()')"/>
114	</xsl:when>
115	<xsl:otherwise>
116	<xsl:value-of select="@to"/>
117	</xsl:otherwise>
118	</xsl:choose>
119	<xsl:text> </xsl:text>
120	<xsl:choose>
121	<xsl:when test="normalize-space(text())">
122	<xsl:value-of select="normalize-space(text())"/>
123	</xsl:when>
124	<xsl:otherwise>
125	<xsl:choose>
126	<xsl:when test="starts-with(@to, '#')">
127	<xsl:value-of select="substring-after(@to, '#')"/>
128	</xsl:when>
129	<xsl:when test="starts-with(@to, '::')">
130	<xsl:value-of select="substring-after(@to, '::')"/>
131	</xsl:when>
132	<xsl:otherwise>
133	<xsl:value-of select="@to"/>
134	</xsl:otherwise>
135	</xsl:choose>
136	</xsl:otherwise>
137	</xsl:choose>
138	<xsl:text>@endlink</xsl:text>
139	<!--
140	* insert a dummy empty B element to distinctly separate @endlink
141	* from the following text
142	-->
143	<xsl:element name="b"/>
144	</xsl:template>
145
146	<!--
147	* note
148	-->
149	<xsl:template match="desc/note">
150	<xsl:if test="not(@internal='yes')">
151	<xsl:text> @note </xsl:text>
152	<xsl:apply-templates/>
153	<xsl:text> </xsl:text>
154	</xsl:if>
155	</xsl:template>
156
157	<!--
158	* see
159	-->
160	<xsl:template match="desc/see">
161	<xsl:text> @see </xsl:text>
162	<xsl:apply-templates/>
163	<xsl:text> </xsl:text>
164	</xsl:template>
165
166
167	<!--
168	* common comment prologue (handles group IDs)
169	-->
170	<xsl:template match="desc" mode="begin">
171	<xsl:param name="id" select="@group \| preceding::descGroup[1]/@id"/>
172	<xsl:text>/** </xsl:text>
173	<xsl:if test="$id">
174	<xsl:value-of select="concat(' @ingroup ',$id,' ')"/>
175	</xsl:if>
176	</xsl:template>
177
178	<!--
179	* common brief comment prologue (handles group IDs)
180	-->
181	<xsl:template match="desc" mode="begin_brief">
182	<xsl:param name="id" select="@group \| preceding::descGroup[1]/@id"/>
183	<xsl:text>/** </xsl:text>
184	<xsl:if test="$id">
185	<xsl:value-of select="concat(' @ingroup ',$id,' ')"/>
186	</xsl:if>
187	<xsl:text> @brief </xsl:text>
188	</xsl:template>
189
190	<!--
191	* common middle part of the comment block
192	-->
193	<xsl:template match="desc" mode="middle">
194	<xsl:apply-templates select="text() \| *[not(self::note or self::see)]"/>
195	<xsl:apply-templates select="note"/>
196	<xsl:apply-templates select="see"/>
197	</xsl:template>
198
199	<!--
200	* result part of the comment block
201	-->
202	<xsl:template match="desc" mode="results">
203	<xsl:if test="result">
204	<xsl:text>
205	@par Expected result codes:
206	</xsl:text>
207	<table>
208	<xsl:for-each select="result">
209	<tr>
210	<xsl:choose>
211	<xsl:when test="ancestor::library/result[@name=current()/@name]">
212	<td><xsl:value-of select=
213	"concat('@link ::',@name,' ',@name,' @endlink')"/></td>
214	</xsl:when>
215	<xsl:otherwise>
216	<td><xsl:value-of select="@name"/></td>
217	</xsl:otherwise>
218	</xsl:choose>
219	<td>
220	<xsl:apply-templates select="text() \| *[not(self::note or self::see or
221	self::result)]"/>
222	</td>
223	</tr>
224	</xsl:for-each>
225	</table>
226	</xsl:if>
227	</xsl:template>
228
229
230	<!--
231	* comment for interfaces
232	-->
233	<xsl:template match="interface/desc">
234	<xsl:apply-templates select="." mode="begin"/>
235	<xsl:apply-templates select="." mode="middle"/>
236	@par Interface ID:
237	<tt>{<xsl:call-template name="string-to-upper">
238	<xsl:with-param name="str" select="../@uuid"/>
239	</xsl:call-template>}</tt>
240	<xsl:text> */ </xsl:text>
241	</xsl:template>
242
243	<!--
244	* comment for attributes
245	-->
246	<xsl:template match="attribute/desc">
247	<xsl:apply-templates select="." mode="begin"/>
248	<xsl:apply-templates select="text() \| *[not(self::note or self::see or self::result)]"/>
249	<xsl:apply-templates select="." mode="results"/>
250	<xsl:apply-templates select="note"/>
251	<xsl:if test="../@mod='ptr'">
252	<xsl:text>
253
254	@warning This attribute is non-scriptable. In particular, this also means that an
255	attempt to get or set it from a process other than the process that has created and
256	owns the object will most likely fail or crash your application.
257	</xsl:text>
258	</xsl:if>
259	<xsl:apply-templates select="see"/>
260	<xsl:text> */ </xsl:text>
261	</xsl:template>
262
263	<!--
264	* comment for methods
265	-->
266	<xsl:template match="method/desc">
267	<xsl:apply-templates select="." mode="begin"/>
268	<xsl:apply-templates select="text() \| *[not(self::note or self::see or self::result)]"/>
269	<xsl:for-each select="../param">
270	<xsl:apply-templates select="desc"/>
271	</xsl:for-each>
272	<xsl:apply-templates select="." mode="results"/>
273	<xsl:apply-templates select="note"/>
274	<xsl:apply-templates select="../param/desc/note"/>
275	<xsl:if test="../param/@mod='ptr'">
276	<xsl:text>
277
278	@warning This method is non-scriptable. In particular, this also means that an
279	attempt to call it from a process other than the process that has created and
280	owns the object will most likely fail or crash your application.
281	</xsl:text>
282	</xsl:if>
283	<xsl:apply-templates select="see"/>
284	<xsl:text> */ </xsl:text>
285	</xsl:template>
286
287	<!--
288	* comment for method parameters
289	-->
290	<xsl:template match="method/param/desc">
291	<xsl:text> @param </xsl:text>
292	<xsl:value-of select="../@name"/>
293	<xsl:text> </xsl:text>
294	<xsl:apply-templates select="text() \| *[not(self::note or self::see)]"/>
295	<xsl:text> </xsl:text>
296	</xsl:template>
297
298	<!--
299	* comment for enums
300	-->
301	<xsl:template match="enum/desc">
302	<xsl:apply-templates select="." mode="begin"/>
303	<xsl:apply-templates select="." mode="middle"/>
304	@par Interface ID:
305	<tt>{<xsl:call-template name="string-to-upper">
306	<xsl:with-param name="str" select="../@uuid"/>
307	</xsl:call-template>}</tt>
308	<xsl:text> */ </xsl:text>
309	</xsl:template>
310
311	<!--
312	* comment for enum values
313	-->
314	<xsl:template match="enum/const/desc">
315	<xsl:apply-templates select="." mode="begin_brief"/>
316	<xsl:apply-templates select="." mode="middle"/>
317	<xsl:text> */ </xsl:text>
318	</xsl:template>
319
320	<!--
321	* comment for result codes
322	-->
323	<xsl:template match="result/desc">
324	<xsl:apply-templates select="." mode="begin_brief"/>
325	<xsl:apply-templates select="." mode="middle"/>
326	<xsl:text> */ </xsl:text>
327	</xsl:template>
328
329	<!--
330	* ignore descGroups by default (processed in /idl)
331	-->
332	<xsl:template match="descGroup"/>
333
334	<!--
335	// templates
336	/////////////////////////////////////////////////////////////////////////////
337	-->
338
339
340	<!--
341	* header
342	-->
343	<xsl:template match="/idl">
344	/*
345	* DO NOT EDIT! This is a generated file.
346	*
347	* Doxygen IDL definition for VirtualBox Main API (COM interfaces)
348	* generated from XIDL (XML interface definition).
349	*
350	* Source : src/VBox/Main/idl/VirtualBox.xidl
351	* Generator : src/VBox/Main/idl/doxygen.xsl
352	*
353	* This IDL is generated using some generic OMG IDL-like syntax SOLELY
354	* for the purpose of generating the documentation using Doxygen and
355	* is not syntactically valid.
356	*
357	* DO NOT USE THIS HEADER IN ANY OTHER WAY!
358	*/
359
360	<!-- general description -->
361	<xsl:text>/** @mainpage </xsl:text>
362	<xsl:apply-templates select="desc" mode="middle"/>
363	<xsl:text> */ </xsl:text>
364
365	<!-- group (module) definitions -->
366	<xsl:for-each select="//descGroup">
367	<xsl:if test="@id and (@title or desc)">
368	<xsl:value-of select="concat('/** @defgroup ',@id,' ',@title)"/>
369	<xsl:apply-templates select="desc" mode="middle"/>
370	<xsl:text> */ </xsl:text>
371	</xsl:if>
372	</xsl:for-each>
373
374	<!-- everything else -->
375	<xsl:apply-templates select="*[not(self::desc)]"/>
376
377	</xsl:template>
378
379
380	<!--
381	* accept all <if>s
382	-->
383	<xsl:template match="if">
384	<xsl:apply-templates/>
385	</xsl:template>
386
387
388	<!--
389	* cpp_quote (ignore)
390	-->
391	<xsl:template match="cpp">
392	</xsl:template>
393
394
395	<!--
396	* #ifdef statement (@if attribute)
397	-->
398	<xsl:template match="@if" mode="begin">
399	<xsl:text>#if </xsl:text>
400	<xsl:value-of select="."/>
401	<xsl:text> </xsl:text>
402	</xsl:template>
403	<xsl:template match="@if" mode="end">
404	<xsl:text>#endif </xsl:text>
405	</xsl:template>
406
407
408	<!--
409	* libraries
410	-->
411	<xsl:template match="library">
412	<!-- result codes -->
413	<xsl:for-each select="result">
414	<xsl:apply-templates select="."/>
415	</xsl:for-each>
416	<!-- all enums go first -->
417	<xsl:apply-templates select="enum \| if/enum"/>
418	<!-- everything else but result codes and enums -->
419	<xsl:apply-templates select="*[not(self::result or self::enum) and
420	not(self::if[result] or self::if[enum])]"/>
421	</xsl:template>
422
423
424	<!--
425	* result codes
426	-->
427	<xsl:template match="result">
428	<xsl:apply-templates select="@if" mode="begin"/>
429	<xsl:apply-templates select="desc"/>
430	<xsl:value-of select="concat('const HRESULT ',@name,' = ',@value,';')"/>
431	<xsl:text> </xsl:text>
432	<xsl:apply-templates select="@if" mode="end"/>
433	</xsl:template>
434
435
436	<!--
437	* interfaces
438	-->
439	<xsl:template match="interface">
440	<xsl:apply-templates select="desc"/>
441	<xsl:text>interface </xsl:text>
442	<xsl:value-of select="@name"/>
443	<xsl:text> : </xsl:text>
444	<xsl:value-of select="@extends"/>
445	<xsl:text> { </xsl:text>
446	<!-- attributes (properties) -->
447	<xsl:apply-templates select="attribute"/>
448	<!-- methods -->
449	<xsl:apply-templates select="method"/>
450	<!-- 'if' enclosed elements, unsorted -->
451	<xsl:apply-templates select="if"/>
452	<!-- -->
453	<xsl:text>}; /* interface </xsl:text>
454	<xsl:value-of select="@name"/>
455	<xsl:text> */ </xsl:text>
456	</xsl:template>
457
458
459	<!--
460	* attributes
461	-->
462	<xsl:template match="interface//attribute">
463	<xsl:apply-templates select="@if" mode="begin"/>
464	<xsl:apply-templates select="desc"/>
465	<xsl:text> </xsl:text>
466	<xsl:if test="@readonly='yes'">
467	<xsl:text>readonly </xsl:text>
468	</xsl:if>
469	<xsl:text>attribute </xsl:text>
470	<xsl:apply-templates select="@type"/>
471	<xsl:text> </xsl:text>
472	<xsl:value-of select="@name"/>
473	<xsl:text>; </xsl:text>
474	<xsl:apply-templates select="@if" mode="end"/>
475	<xsl:text> </xsl:text>
476	</xsl:template>
477
478	<!--
479	* methods
480	-->
481	<xsl:template match="interface//method">
482	<xsl:apply-templates select="@if" mode="begin"/>
483	<xsl:apply-templates select="desc"/>
484	<xsl:text> void </xsl:text>
485	<xsl:value-of select="@name"/>
486	<xsl:if test="param">
487	<xsl:text> ( </xsl:text>
488	<xsl:for-each select="param [position() != last()]">
489	<xsl:text> </xsl:text>
490	<xsl:apply-templates select="."/>
491	<xsl:text>, </xsl:text>
492	</xsl:for-each>
493	<xsl:text> </xsl:text>
494	<xsl:apply-templates select="param [last()]"/>
495	<xsl:text> ); </xsl:text>
496	</xsl:if>
497	<xsl:if test="not(param)">
498	<xsl:text>(); </xsl:text>
499	</xsl:if>
500	<xsl:apply-templates select="@if" mode="end"/>
501	<xsl:text> </xsl:text>
502	</xsl:template>
503
504
505	<!--
506	* co-classes
507	-->
508	<xsl:template match="module/class">
509	<!-- class and contract id: later -->
510	<!-- CLSID_xxx declarations for XPCOM, for compatibility with Win32: later -->
511	</xsl:template>
512
513
514	<!--
515	* enums
516	-->
517	<xsl:template match="enum">
518	<xsl:apply-templates select="desc"/>
519	<xsl:text>enum </xsl:text>
520	<xsl:value-of select="@name"/>
521	<xsl:text> { </xsl:text>
522	<xsl:for-each select="const">
523	<xsl:apply-templates select="desc"/>
524	<xsl:text> </xsl:text>
525	<xsl:value-of select="../@name"/>
526	<xsl:text>_</xsl:text>
527	<xsl:value-of select="@name"/> = <xsl:value-of select="@value"/>
528	<xsl:text>, </xsl:text>
529	</xsl:for-each>
530	<xsl:text>}; </xsl:text>
531	</xsl:template>
532
533
534	<!--
535	* method parameters
536	-->
537	<xsl:template match="method/param">
538	<xsl:choose>
539	<xsl:when test="@dir='in'">in </xsl:when>
540	<xsl:when test="@dir='out'">out </xsl:when>
541	<xsl:when test="@dir='return'">[retval] out </xsl:when>
542	<xsl:otherwise>in</xsl:otherwise>
543	</xsl:choose>
544	<xsl:apply-templates select="@type"/>
545	<xsl:text> </xsl:text>
546	<xsl:value-of select="@name"/>
547	</xsl:template>
548
549
550	<!--
551	* attribute/parameter type conversion
552	-->
553	<xsl:template match="attribute/@type \| param/@type">
554	<xsl:variable name="self_target" select="current()/ancestor::if/@target"/>
555
556	<xsl:choose>
557	<!-- modifiers (ignored for 'enumeration' attributes)-->
558	<xsl:when test="name(current())='type' and ../@mod">
559	<xsl:choose>
560	<xsl:when test="../@mod='ptr'">
561	<xsl:choose>
562	<!-- standard types -->
563	<!--xsl:when test=".='result'">??</xsl:when-->
564	<xsl:when test=".='boolean'">booleanPtr</xsl:when>
565	<xsl:when test=".='octet'">octetPtr</xsl:when>
566	<xsl:when test=".='short'">shortPtr</xsl:when>
567	<xsl:when test=".='unsigned short'">ushortPtr</xsl:when>
568	<xsl:when test=".='long'">longPtr</xsl:when>
569	<xsl:when test=".='long long'">llongPtr</xsl:when>
570	<xsl:when test=".='unsigned long'">ulongPtr</xsl:when>
571	<xsl:when test=".='unsigned long long'">ullongPtr</xsl:when>
572	<xsl:otherwise>
573	<xsl:message terminate="yes">
574	<xsl:value-of select="concat(../../../@name,'::',../../@name,'::',../@name,': ')"/>
575	<xsl:text>attribute 'mod=</xsl:text>
576	<xsl:value-of select="concat('"',../@mod,'"')"/>
577	<xsl:text>' cannot be used with type </xsl:text>
578	<xsl:value-of select="concat('"',current(),'"!')"/>
579	</xsl:message>
580	</xsl:otherwise>
581	</xsl:choose>
582	</xsl:when>
583	<xsl:when test="../@mod='string'">
584	<xsl:choose>
585	<!-- standard types -->
586	<!--xsl:when test=".='result'">??</xsl:when-->
587	<xsl:when test=".='uuid'">wstringUUID</xsl:when>
588	<xsl:otherwise>
589	<xsl:message terminate="yes">
590	<xsl:value-of select="concat(../../../@name,'::',../../@name,'::',../@name,': ')"/>
591	<xsl:text>attribute 'mod=</xsl:text>
592	<xsl:value-of select="concat('"',../@mod,'"')"/>
593	<xsl:text>' cannot be used with type </xsl:text>
594	<xsl:value-of select="concat('"',current(),'"!')"/>
595	</xsl:message>
596	</xsl:otherwise>
597	</xsl:choose>
598	</xsl:when>
599	<xsl:otherwise>
600	<xsl:message terminate="yes">
601	<xsl:value-of select="concat(../../../@name,'::',../../@name,'::',../@name,': ')"/>
602	<xsl:value-of select="concat('value "',../@mod,'" ')"/>
603	<xsl:text>of attribute 'mod' is invalid!</xsl:text>
604	</xsl:message>
605	</xsl:otherwise>
606	</xsl:choose>
607	</xsl:when>
608	<!-- no modifiers -->
609	<xsl:otherwise>
610	<xsl:choose>
611	<!-- standard types -->
612	<xsl:when test=".='result'">result</xsl:when>
613	<xsl:when test=".='boolean'">boolean</xsl:when>
614	<xsl:when test=".='octet'">octet</xsl:when>
615	<xsl:when test=".='short'">short</xsl:when>
616	<xsl:when test=".='unsigned short'">unsigned short</xsl:when>
617	<xsl:when test=".='long'">long</xsl:when>
618	<xsl:when test=".='long long'">long long</xsl:when>
619	<xsl:when test=".='unsigned long'">unsigned long</xsl:when>
620	<xsl:when test=".='unsigned long long'">unsigned long long</xsl:when>
621	<xsl:when test=".='char'">char</xsl:when>
622	<xsl:when test=".='wchar'">wchar</xsl:when>
623	<xsl:when test=".='string'">string</xsl:when>
624	<xsl:when test=".='wstring'">wstring</xsl:when>
625	<!-- UUID type -->
626	<xsl:when test=".='uuid'">uuid</xsl:when>
627	<!-- system interface types -->
628	<xsl:when test=".='$unknown'">$unknown</xsl:when>
629	<xsl:otherwise>
630	<xsl:choose>
631	<!-- enum types -->
632	<xsl:when test="
633	(ancestor::library/enum[@name=current()]) or
634	(ancestor::library/if[@target=$self_target]/enum[@name=current()])
635	">
636	<xsl:value-of select="."/>
637	</xsl:when>
638	<!-- custom interface types -->
639	<xsl:when test="
640	((ancestor::library/interface[@name=current()]) or
641	(ancestor::library/if[@target=$self_target]/interface[@name=current()])
642	)
643	">
644	<xsl:value-of select="."/>
645	</xsl:when>
646	<!-- other types -->
647	<xsl:otherwise>
648	<xsl:message terminate="yes">
649	<xsl:text>Unknown parameter type: </xsl:text>
650	<xsl:value-of select="."/>
651	</xsl:message>
652	</xsl:otherwise>
653	</xsl:choose>
654	</xsl:otherwise>
655	</xsl:choose>
656	</xsl:otherwise>
657	</xsl:choose>
658	<xsl:if test="../@safearray='yes'">
659	<xsl:text>[]</xsl:text>
660	</xsl:if>
661	</xsl:template>
662
663	</xsl:stylesheet>
664

Note: See TracBrowser for help on using the repository browser.

source: vbox/trunk/src/VBox/Main/idl/doxygen.xsl@ 64226

Download in other formats: